@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}).
To that end, all the command-line tools can be used even if you have not
run @code{make install}. To do that, prefix each command with
@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
-top build tree of Guix), as in:
+top build tree of Guix), as in@footnote{The @option{-E} flag to
+@command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
+such that @command{guix-daemon} and the tools it uses can find the Guile
+modules they need.}:
@example
-$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
+$ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
$ ./pre-inst-env guix build hello
@end example
s-expression or wrapping it, swallowing or rejecting the following
s-expression, etc.
+@cindex code snippets
+@cindex templates
+@cindex reducing boilerplate
+We also provide templates for common git commit messages and package
+definitions in the @file{etc/snippets} directory. These templates can
+be used with @url{http://joaotavora.github.io/yasnippet/, YASnippet} to
+expand short trigger strings to interactive text snippets. You may want
+to add the snippets directory to the @var{yas-snippet-dirs} variable in
+Emacs.
+
+@lisp
+;; @r{Assuming the Guix checkout is in ~/src/guix.}
+(with-eval-after-load 'yasnippet
+ (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))
+@end lisp
+
+The commit message snippets depend on @url{https://magit.vc/, Magit} to
+display staged files. When editing a commit message type @code{add}
+followed by @kbd{TAB} to insert a commit message template for adding a
+package; type @code{update} followed by @kbd{TAB} to insert a template
+for updating a package.
+
+The main snippet for @code{scheme-mode} is triggered by typing
+@code{package...} followed by @kbd{TAB}. This snippet also inserts the
+trigger string @code{origin...}, which can be expanded further. The
+@code{origin} snippet in turn may insert other trigger strings ending on
+@code{...}, which also can be expanded further.
+
@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
+
+@cindex Vim, Scheme code editing
+If you are editing code with Vim, we recommend that you run @code{:set
+autoindent} so that your code is automatically indented as you type.
+Additionally,
+@uref{https://www.vim.org/scripts/script.php?script_id=3998,
+@code{paredit.vim}} may help you deal with all these parentheses.
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