[PATCH] doc: Update contribution guidelines on patches, etc.

[Liliana Marie Prikler]

* doc/contributing.texi ("Snippets versus Phases"): Replaced with...
("Modifying Sources"): ... this.  List more use cases and some principles.
---
 doc/contributing.texi | 85 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 72 insertions(+), 13 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 02c7c5ae59..7a03715abf 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -441,7 +441,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.
+* Modifying Sources::           When to use patches, snippets, or build phases.
 * Emacs Packages::              Your Elisp fix.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
@@ -698,20 +698,79 @@ Gettext}):
 for the X11 resize-and-rotate (RandR) extension. @dots{}")
 @end lisp
 
-@node Snippets versus Phases
-@subsection Snippets versus Phases
+@node Modifying Sources
+@subsection Modifying Sources
 
+@cindex patches, when to use
 @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}).
+
+Guix has three main ways of modifying the source code of a package,
+that you as a packager may use.  Each one has its strengths and
+drawbacks, along with intended and historically derived use cases.
+These are
+
+@table @asis
+
+@item patches
+If your package has a bug that takes multiple lines to fix, or a fix
+has already been accepted upstream, patches are the preferred way of
+eliminating said bug.  Refer to the @code{origin} record documentation
+(particularly the fields @code{patches}, @code{patch-inputs}, and
+@code{patch-flags}) for more information (@pxref{origin Reference}).
+When adding a patch, do not forget to also list it in
+@code{dist_patch_DATA} of @file{gnu/local.mk}
+
+Patches are limited in that they lack the expressiveness of Guile.
+If all changes are constrained to single lines, a patch might be much
+larger than the equivalent @code{substitute*}.  Furthermore, building
+a package with an additional patch causes two new derivations to be
+built: First the source, then the package.
+
+@item snippets
+If your package contains non-free sources, these need to be removed
+through a snippet.  This snippet should not only remove the sources in
+question, but also references to the removed sources in build scripts,
+documentation, and so on. @ref{Software Freedom}
+
+If your package bundles external libraries, snippets are the preferred
+way of removing said them.  Unlike with non-free sources, it is not a
+requirement to remove @emph{all} bundled libraries, although doing so
+is very much preferred.  Bundled libraries that are kept should be
+clearly indicated, preferrably with a reason as to why the bundled copy
+remains.  As with non-free sources, references to the removed libraries
+should also be updated in the snippet.
+
+Refer to the @code{origin} record documentation
+(particularly the fields @code{snippet} and @code{modules}), for more
+information (@pxref{origin Reference}).
+
+Snippets are limited in that @code{substitute*} can not deal with
+multi-line changes well.  Furthermore, as with patches, modifying the
+snippets causes two derivations to be built.
+
+@item build phases
+For modifications that retain the intended functionality of the
+package, build phases (usually between @code{unpack} and
+@code{configure}, sometimes between @code{configure} and @code{build})
+can be used.  Such changes include, but are not limited to fixes of the
+build script(s) or embeddings of store paths (e.g. replacement of
+@file{/bin/sh} with @code{(search-input-file inputs "bin/sh")}).
+
+If you need to embed a store path, do so only inside a build phase.
+A workaround for patches that span multiple lines, is to use a variable
+such as @code{@@store_path@@} inside the patch and substitute the actual
+store path at build time via @code{substitute*}.
+
+Build phases are limited in that they do not modify the source
+derivation.  Thus, they are inadequate for changes that are to be
+reflected in the source code.  On the other hand, they only cause a
+single rebuild and are thus slightly easier to debug than phases and
+snippets.
+
+@end table
+
+If your change does not neatly fit in any of the categories above, it
+is usually a matter of preference or convenience.
 
 @node Emacs Packages
 @subsection Emacs Packages
-- 
2.37.0