From 71e746cc63a932afea0d41652c8c297d796bccf7 Mon Sep 17 00:00:00 2001 From: Maxim Cournoyer Date: Fri, 11 Sep 2020 14:08:34 -0400 Subject: doc: Document the use of snippets vs phases. * doc/contributing.texi (Snippets versus phases): New section. --- doc/contributing.texi | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index aedcb334c4..b18ffa1e57 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -369,6 +369,7 @@ needed is to review and apply the patch. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. +* Snippets versus Phases:: Whether to use a snippet, or a build phase. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. @@ -599,6 +600,20 @@ Gettext}): for the X11 resize-and-rotate (RandR) extension. @dots{}") @end example +@node Snippets versus Phases +@subsection Snippets versus Phases + +@cindex snippets, when to use +The boundary between using an origin snippet versus a build phase to +modify the sources of a package can be elusive. Origin snippets are +typically used to remove unwanted files such as bundled libraries, +nonfree sources, or to apply simple substitutions. The source derived +from an origin should produce a source that can be used to build the +package on any system that the upstream package supports (i.e., act as +the corresponding source). In particular, origin snippets must not +embed store items in the sources; such patching should rather be done +using build phases. Refer to the @code{origin} record documentation for +more information (@pxref{origin Reference}). @node Python Modules @subsection Python Modules -- cgit v1.2.3