doc: Add Emacs packaging guidelines.

* doc/contributing.texi (Emacs Packages): New subsection.

2 files changed, 42 insertions, 0 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 78d9990b30..6500bfa3a1 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -391,6 +391,7 @@ needed is to review and apply the patch.
 * 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.
+* Emacs Packages::              Your Elisp fix.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
 * Java Packages::               Coffee break.
@@ -636,6 +637,46 @@ 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 Emacs Packages
+@subsection Emacs Packages
+
+@cindex emacs, packaging
+@cindex elisp, packaging
+Emacs packages should preferably use the Emacs build system
+(@pxref{emacs-build-system}), for uniformity and the benefits provided
+by its build phases, such as the auto-generation of the autoloads file
+and the byte compilation of the sources.  Because there are no
+standardized way to run a test suite for Emacs packages, tests are
+disabled by default.  When a test suite is available, it should be
+enabled by setting the @code{#:tests?}  argument to @code{#true}.  By
+default, the command to run the test is @command{make check}, but any
+command can be specified via the @code{#:test-command} argument.  The
+@code{#:test-command} argument expects a list containing a command and
+its arguments, to be invoked during the @code{'check} phase.
+
+The Elisp dependencies of Emacs packages are typically provided as
+@code{propagated-inputs} when required at run time.  As for other
+packages, build or test dependencies should be specified as
+@code{native-inputs}.
+
+Emacs packages sometimes depend on resources directories that should be
+installed along the Elisp files.  The @code{#:include} argument can be
+used for that purpose, by specifying a list of regexps to match.  The
+best practice when using the @code{#:include} argument is to extend
+rather than override its default value (accessible via the
+@code{%default-include} variable).  As an example, a yasnippet extension
+package typically include a @file{snippets} directory, which could be
+copied to the installation directory using:
+
+@lisp
+#:include (cons "^snippets/" %default-include))
+@end lisp
+
+When encountering problems, it is wise to check for the presence of the
+@code{Package-Requires} extension header in the package main source
+file, and whether any dependencies and their versions listed therein are
+satisfied.
+
 @node Python Modules
 @subsection Python Modules
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 38927bc0b5..392baf5910 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7930,6 +7930,7 @@ Which D compiler is used can be specified with the @code{#:ldc}
 parameter which defaults to @code{ldc}.
 @end defvr
 
+@anchor{emacs-build-system}
 @defvr {Scheme Variable} emacs-build-system
 This variable is exported by @code{(guix build-system emacs)}.  It
 implements an installation procedure similar to the packaging system