doc: Suggest keeping record type descriptors private.

* doc/contributing.texi (Data Types and Pattern Matching): Add paragraph
about keeping RTDs private.

Suggested-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>

1 files changed, 11 insertions, 0 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 86fc65eb2d..864190b119 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1308,6 +1308,17 @@ Guile Reference Manual}); pattern matching for records is better done
 using @code{match-record} from @code{(guix records)}, which, unlike
 @code{match}, verifies field names at macro-expansion time.
 
+When defining a new record type, keep the @dfn{record type descriptor}
+(RTD) private (@pxref{Records,,, guile, GNU Guile Reference Manual}, for
+more on records and RTDs).  As an example, the @code{(guix packages)}
+module defines @code{<package>} as the RTD for package records but it
+does not export it; instead, it exports a type predicate, a constructor,
+and field accessors.  Exporting RTDs would make it harder to change the
+application binary interface (because code in other modules might be
+matching fields by position) and would make it trivial for users to
+forge records of that type, bypassing any checks we may have in the
+official constructor (such as ``field sanitizers'').
+
 @node Formatting Code
 @subsection Formatting Code