From 7b710836a1c7cb921f54ead64f465bcc5333d076 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Thu, 5 Oct 2023 16:15:24 +0200 Subject: [PATCH] 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 --- doc/contributing.texi | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index 86fc65eb2d091e6fa73f1ae080a3c19fa6e7f239..864190b1190cdc4cfb598804c29d75c40acb2e07 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{} 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