@url{http://contributor-covenant.org/}. You can find a local version in
the @file{CODE-OF-CONDUCT} file in the source tree.
+Contributors are not required to use their legal name in patches and
+on-line communication; they can use any name or pseudonym of their
+choice.
+
@menu
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
@section Building from Git
If you want to hack Guix itself, it is recommended to use the latest
-version from the Git repository. When building Guix from a checkout,
+version from the Git repository:
+
+@example
+git clone https://git.savannah.gnu.org/git/guix.git
+@end example
+
+When building Guix from a checkout,
the following packages are required in addition to those mentioned in
the installation instructions (@pxref{Requirements}).
@xref{Macro Search Path,,, automake, The GNU Automake Manual}, for
more information.
-Then, run @command{./configure} as usual.
+Then, run @command{./configure} as usual. Make sure to pass
+@code{--localstatedir=@var{directory}} where @var{directory} is the
+@code{localstatedir} value used by your current installation (@pxref{The
+Store}, for information about this).
-Finally, you have to invoke @code{make check} to run tests. If anything
+Finally, you have to invoke @code{make check} to run tests
+(@pxref{Running the Test Suite}). If anything
fails, take a look at installation instructions (@pxref{Installation})
or send a message to the @email{guix-devel@@gnu.org, mailing list}.
Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the
local source tree; it simply updates the @file{~/.config/guix/latest}
symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if
-you want to upgrade your local source tree.
+you want to upgrade your local source tree.@footnote{If you would like
+to set up @command{guix} to use your Git checkout, you can point the
+@file{~/.config/guix/latest} symlink to your Git checkout directory.
+If you are the sole user of your system, you may also consider pointing
+the @file{/root/.config/guix/latest} symlink to point to
+@file{~/.config/guix/latest}; this way it will always use the same
+@command{guix} as your user does.}
@node The Perfect Setup
s-expression or wrapping it, swallowing or rejecting the following
s-expression, etc.
-GNU Guix also comes with a minor mode that provides some additional
-functionality for Scheme buffers (@pxref{Emacs Development}).
-
@node Coding Style
@section Coding Style
@node Formatting Code
@subsection Formatting Code
+@cindex formatting code
+@cindex coding style
When writing Scheme code, we follow common wisdom among Scheme
programmers. In general, we follow the
@url{http://mumble.net/~campbell/scheme/style.txt, Riastradh's Lisp
Some special forms introduced in Guix, such as the @code{substitute*}
macro, have special indentation rules. These are defined in the
-@file{.dir-locals.el} file, which Emacs automatically uses. If you do
-not use Emacs, please make sure to let your editor know the rules.
+@file{.dir-locals.el} file, which Emacs automatically uses. Also note
+that Emacs-Guix provides @code{guix-devel-mode} mode that indents and
+highlights Guix code properly (@pxref{Development,,, emacs-guix, The
+Emacs-Guix Reference Manual}).
+
+@cindex indentation, of code
+@cindex formatting, of code
+If you do not use Emacs, please make sure to let your editor knows these
+rules. To automatically indent a package definition, you can also run:
+
+@example
+./etc/indent-code.el gnu/packages/@var{file}.scm @var{package}
+@end example
+
+@noindent
+This automatically indents the definition of @var{package} in
+@file{gnu/packages/@var{file}.scm} by running Emacs in batch mode. To
+indent a whole file, omit the second argument:
+
+@example
+./etc/indent-code.el gnu/services/@var{file}.scm
+@end example
We require all top-level procedures to carry a docstring. This
requirement can be relaxed for simple private procedures in the
Development is done using the Git distributed version control system.
Thus, access to the repository is not strictly necessary. We welcome
contributions in the form of patches as produced by @code{git
-format-patch} sent to the @email{guix-devel@@gnu.org, mailing list}.
+format-patch} sent to the @email{guix-patches@@gnu.org} mailing list.
+
+This mailing list is backed by a Debbugs instance accessible at
+@uref{https://bugs.gnu.org/guix-patches}, which allows us to keep track
+of submissions. Each message sent to that mailing list gets a new
+tracking number assigned; people can then follow up on the submission by
+sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
+the tracking number (@pxref{Sending a Patch Series}).
+
Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
standards, GNU Coding Standards}); you can check the commit history for
examples.
please run through this check list:
@enumerate
+@item
+If the authors of the packaged software provide a cryptographic
+signature for the release tarball, make an effort to verify the
+authenticity of the archive. For a detached GPG signature file this
+would be done with the @code{gpg --verify} command.
+
@item
Take some time to provide an adequate synopsis and description for the
package. @xref{Synopses and Descriptions}, for some guidelines.
Make sure the package builds on your platform, using @code{guix build
@var{package}}.
+@item
+@cindex bundling
+Make sure the package does not use bundled copies of software already
+available as separate packages.
+
+Sometimes, packages include copies of the source code of their
+dependencies as a convenience for users. However, as a distribution, we
+want to make sure that such packages end up using the copy we already
+have in the distribution, if there is one. This improves resource usage
+(the dependency is built and stored only once), and allows the
+distribution to make transverse changes such as applying security
+updates for a given software package in a single place and have them
+affect the whole system---something that bundled copies prevent.
+
@item
Take a look at the profile reported by @command{guix size}
(@pxref{Invoking guix size}). This will allow you to notice references
not affected by the change; @code{guix refresh --list-dependent
@var{package}} will help you do that (@pxref{Invoking guix refresh}).
+@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>.
+@cindex branching strategy
+@cindex rebuild scheduling strategy
+Depending on the number of dependent packages and thus the amount of
+rebuilding induced, commits go to different branches, along these lines:
+
+@table @asis
+@item 300 dependent packages or less
+@code{master} branch (non-disruptive changes).
+
+@item between 300 and 1,200 dependent packages
+@code{staging} branch (non-disruptive changes). This branch is intended
+to be merged in @code{master} every 3 weeks or so. Topical changes
+(e.g., an update of the GNOME stack) can instead go to a specific branch
+(say, @code{gnome-updates}).
+
+@item more than 1,200 dependent packages
+@code{core-updates} branch (may include major and potentially disruptive
+changes). This branch is intended to be merged in @code{master} every
+2.5 months or so.
+@end table
+
+All these branches are tracked by our build farm
+and merged into @code{master} once
+everything has been successfully built. This allows us to fix issues
+before they hit users, and to reduce the window during which pre-built
+binaries are not available.
+
@item
@cindex determinism, of build processes
@cindex reproducible builds, checking
extensions---or to the operating system kernel---e.g., reliance on
@code{uname} or @file{/proc} files.
+@item
+When writing documentation, please use gender-neutral wording when
+referring to people, such as
+@uref{https://en.wikipedia.org/wiki/Singular_they, singular
+``they''@comma{} ``their''@comma{} ``them''}, and so forth.
+
+@item
+Verify that your patch contains only one set of related changes.
+Bundling unrelated changes together makes reviewing harder and slower.
+
+Examples of unrelated changes include the addition of several packages,
+or a package update along with fixes to that package.
+
+@item
+Please follow our code formatting rules, possibly running the
+@command{etc/indent-code.el} script to do that automatically for you
+(@pxref{Formatting Code}).
+
@end enumerate
When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
a subject. You may use your email client or the @command{git
-send-email} command.
+send-email} command (@pxref{Sending a Patch Series}). We prefer to get
+patches in plain text messages, either inline or as MIME attachments.
+You are advised to pay attention if your email client changes anything
+like line breaks or indentation which could potentially break the
+patches.
+
+When a bug is resolved, please close the thread by sending an email to
+@email{@var{NNN}-done@@debbugs.gnu.org}.
+
+@unnumberedsubsec Sending a Patch Series
+@anchor{Sending a Patch Series}
+@cindex patch series
+@cindex @code{git send-email}
+@cindex @code{git-send-email}
+
+When sending a patch series (e.g., using @code{git send-email}), please
+first send one message to @email{guix-patches@@gnu.org}, and then send
+subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
+they are kept together. See
+@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
+for more information.
+@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html