@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}).
@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.
not affected by the change; @code{guix refresh --list-dependent
@var{package}} will help you do that (@pxref{Invoking guix refresh}).
-Packages with roughly 100 dependents or more usually have to be
-committed to a separate branch. That branch can then be built
-separately by our build farm, and later merged into @code{master} once
+@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.
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. 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.
+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
HCoop / jackhill / guix / guix.git / blobdiff