Contributing
************

This project is a cooperative effort, and we need your help to make it grow!  Please get in touch with us on guix-devel@gnu.org and #guix on the Freenode IRC network.  We welcome ideas, bug reports, patches, and anything that may be helpful to the project.  We particularly welcome help on packaging (see Packaging Guidelines).

We want to provide a warm, friendly, and harassment-free environment, so that anyone can contribute to the best of their abilities.  To this end our project uses a ``Contributor Covenant'', which was adapted from http://contributor-covenant.org/.  You can find a local version in the 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.

Building from Git
=================

If you want to hack Guix itself, it is recommended to use the latest version from the Git repository:

     git clone https://git.savannah.gnu.org/git/guix.git

When building Guix from a checkout, the following packages are required in addition to those mentioned in the installation instructions (see Requirements).

  * GNU Autoconf (http://gnu.org/software/autoconf/);

  * GNU Automake (http://gnu.org/software/automake/);

  * GNU Gettext (http://gnu.org/software/gettext/);

  * GNU Texinfo (http://gnu.org/software/texinfo/);

  * Graphviz (http://www.graphviz.org/);

  * GNU Help2man (optional) (http://www.gnu.org/software/help2man/).

The easiest way to set up a development environment for Guix is, of course, by using Guix!  The following command starts a new shell where all the dependencies and appropriate environment variables are set up to hack on Guix:

     guix environment guix

See Invoking guix environment, for more information on that command. Extra dependencies can be added with --ad-hoc:

     guix environment guix --ad-hoc help2man git strace

Run ./bootstrap to generate the build system infrastructure using Autoconf and Automake.  If you get an error like this one:

     configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES

it probably means that Autoconf couldn’t find pkg.m4, which is provided by pkg-config.  Make sure that pkg.m4 is available.  The same holds for the guile.m4 set of macros provided by Guile.  For instance, if you installed Automake in /usr/local, it wouldn’t look for .m4 files in /usr/share.  In that case, you have to invoke the following command:

     export ACLOCAL_PATH=/usr/share/aclocal

See Macro Search Path (The GNU Automake Manual), for more information.

Then, run ./configure as usual.  Make sure to pass --localstatedir=DIRECTORY where DIRECTORY is the localstatedir value used by your current installation (see The Store, for information about this).

Finally, you have to invoke make check to run tests (see Running the Test Suite).  If anything fails, take a look at installation instructions (see Installation) or send a message to the mailing list.

Running Guix Before It Is Installed
===================================

In order to keep a sane working environment, you will find it useful to test the changes made in your local source tree checkout without actually installing them.  So that you can distinguish between your ``end-user'' hat and your ``motley'' costume.

To that end, all the command-line tools can be used even if you have not run make install.  To do that, prefix each command with ./pre-inst-env (the pre-inst-env script lives in the top build tree of Guix), as in (The -E flag to sudo guarantees that GUILE_LOAD_PATH is correctly set such that guix-daemon and the tools it uses can find the Guile modules they need.):

     $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild
     $ ./pre-inst-env guix build hello

Similarly, for a Guile session using the Guix modules:

     $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'

     ;;; ("x86_64-linux")

... and for a REPL (see Using Guile Interactively (Guile Reference Manual)):

     $ ./pre-inst-env guile
     scheme@(guile-user)> ,use(guix)
     scheme@(guile-user)> ,use(gnu)
     scheme@(guile-user)> (define snakes
                            (fold-packages
                              (lambda (package lst)
                                (if (string-prefix? "python"
                                                    (package-name package))
                                    (cons package lst)
                                    lst))
                              '()))
     scheme@(guile-user)> (length snakes)
     $1 = 361

The pre-inst-env script sets up all the environment variables necessary to support this, including PATH and GUILE_LOAD_PATH.

Note that ./pre-inst-env guix pull does not upgrade the local source tree; it simply updates the ~/.config/guix/latest symlink (see Invoking guix pull).  Run git pull instead if you want to upgrade your local source tree. (If you would like to set up guix to use your Git checkout, you can point the ~/.config/guix/latest symlink to your Git checkout directory. If you are the sole user of your system, you may also consider pointing the /root/.config/guix/latest symlink to point to ~/.config/guix/latest; this way it will always use the same guix as your user does.)

The Perfect Setup
=================

The Perfect Setup to hack on Guix is basically the perfect setup used for Guile hacking (see Using Guile in Emacs (Guile Reference Manual)).  First, you need more than an editor, you need Emacs (http://www.gnu.org/software/emacs), empowered by the wonderful Geiser (http://nongnu.org/geiser/).

Geiser allows for interactive and incremental development from within Emacs: code compilation and evaluation from within buffers, access to on-line documentation (docstrings), context-sensitive completion, M-. to jump to an object definition, a REPL to try out your code, and more (see Introduction (Geiser User Manual)).  For convenient Guix development, make sure to augment Guile’s load path so that it finds source files from your checkout:

     ;; Assuming the Guix checkout is in ~/src/guix.
     (with-eval-after-load 'geiser-guile
       (add-to-list 'geiser-guile-load-path "~/src/guix"))

To actually edit the code, Emacs already has a neat Scheme mode.  But in addition to that, you must not miss Paredit (http://www.emacswiki.org/emacs/ParEdit).  It provides facilities to directly operate on the syntax tree, such as raising an s-expression or wrapping it, swallowing or rejecting the following s-expression, etc.

We also provide templates for common git commit messages and package definitions in the etc/snippets directory.  These templates can be used with YASnippet (http://joaotavora.github.io/yasnippet/) to expand short trigger strings to interactive text snippets.  You may want to add the snippets directory to the YAS-SNIPPET-DIRS variable in Emacs.

     ;; Assuming the Guix checkout is in ~/src/guix.
     (with-eval-after-load 'yasnippet
       (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets"))

The commit message snippets depend on Magit (https://magit.vc/) to display staged files.  When editing a commit message type add followed by TAB to insert a commit message template for adding a package; type update followed by TAB to insert a template for updating a package.

The main snippet for scheme-mode is triggered by typing package... followed by TAB.  This snippet also inserts the trigger string origin..., which can be expanded further.  The origin snippet in turn may insert other trigger strings ending on ..., which also can be expanded further.

Coding Style
============

In general our code follows the GNU Coding Standards (see GNU Coding Standards).  However, they do not say much about Scheme, so here are some additional rules.

Programming Paradigm
--------------------

Scheme code in Guix is written in a purely functional style.  One exception is code that involves input/output, and procedures that implement low-level concepts, such as the memoize procedure.

Modules
-------

Guile modules that are meant to be used on the builder side must live in the (guix build ...) name space.  They must not refer to other Guix or GNU modules.  However, it is OK for a ``host-side'' module to use a build-side module.

Modules that deal with the broader GNU system should be in the (gnu ...) name space rather than (guix ...).

Data Types and Pattern Matching
-------------------------------

The tendency in classical Lisp is to use lists to represent everything, and then to browse them ``by hand'' using car, cdr, cadr, and co.  There are several problems with that style, notably the fact that it is hard to read, error-prone, and a hindrance to proper type error reports.

Guix code should define appropriate data types (for instance, using define-record-type*) rather than abuse lists.  In addition, it should use pattern matching, via Guile’s (ice-9 match) module, especially when matching lists.

Formatting Code
---------------

When writing Scheme code, we follow common wisdom among Scheme programmers.  In general, we follow the Riastradh's Lisp Style Rules (http://mumble.net/~campbell/scheme/style.txt).  This document happens to describe the conventions mostly used in Guile’s code too.  It is very thoughtful and well written, so please do read it.

Some special forms introduced in Guix, such as the substitute* macro, have special indentation rules.  These are defined in the .dir-locals.el file, which Emacs automatically uses.  Also note that Emacs-Guix provides guix-devel-mode mode that indents and highlights Guix code properly (see Development (The Emacs-Guix Reference Manual)).

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:

     ./etc/indent-code.el gnu/packages/FILE.scm PACKAGE

This automatically indents the definition of PACKAGE in gnu/packages/FILE.scm by running Emacs in batch mode.  To indent a whole file, omit the second argument:

     ./etc/indent-code.el gnu/services/FILE.scm

We require all top-level procedures to carry a docstring.  This requirement can be relaxed for simple private procedures in the (guix build ...) name space, though.

Procedures should not have more than four positional parameters.  Use keyword parameters for procedures that take more than four parameters.

Submitting Patches
==================

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 git format-patch sent to the guix-patches@gnu.org mailing list.

This mailing list is backed by a Debbugs instance accessible at 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 NNN@debbugs.gnu.org, where NNN is the tracking number (see Sending a Patch Series).

Please write commit logs in the ChangeLog format (see Change Logs (GNU Coding Standards)); you can check the commit history for examples.

Before submitting a patch that adds or modifies a package definition, please run through this check list:

 1. 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 gpg --verify command.

 2. Take some time to provide an adequate synopsis and description for the package.  See Synopses and Descriptions, for some guidelines.

 3. Run guix lint PACKAGE, where PACKAGE is the name of the new or modified package, and fix any errors it reports (see Invoking guix lint).

 4. Make sure the package builds on your platform, using guix build PACKAGE.

 5. 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.

 6. Take a look at the profile reported by guix size (see Invoking guix size).  This will allow you to notice references to other packages unwillingly retained.  It may also help determine whether to split the package (see Packages with Multiple Outputs), and which optional dependencies should be used.

 7. For important changes, check that dependent package (if applicable) are not affected by the change; guix refresh --list-dependent PACKAGE will help you do that (see Invoking guix refresh).

     Depending on the number of dependent packages and thus the amount of rebuilding induced, commits go to different branches, along these lines:

     300 dependent packages or less
          master branch (non-disruptive changes).

     between 300 and 1,200 dependent packages
          staging branch (non-disruptive changes).  This branch is intended to be merged in master every 3 weeks or so.  Topical changes (e.g., an update of the GNOME stack) can instead go to a specific branch (say, gnome-updates).

     more than 1,200 dependent packages
          core-updates branch (may include major and potentially disruptive changes).  This branch is intended to be merged in master every 2.5 months or so.

     All these branches are tracked by our build farm and merged into 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.

 8. Check whether the package's build process is deterministic.  This typically means checking whether an independent build of the package yields the exact same result that you obtained, bit for bit.

     A simple way to do that is by building the same package several times in a row on your machine (see Invoking guix build):

          guix build --rounds=2 my-package

     This is enough to catch a class of common non-determinism issues, such as timestamps or randomly-generated output in the build result.

     Another option is to use guix challenge (see Invoking guix challenge).  You may run it once the package has been committed and built by hydra.gnu.org to check whether it obtains the same result as you did.  Better yet: Find another machine that can build it and run guix publish.  Since the remote build machine is likely different from yours, this can catch non-determinism issues related to the hardware---e.g., use of different instruction set extensions---or to the operating system kernel---e.g., reliance on uname or /proc files.

 9. When writing documentation, please use gender-neutral wording when referring to people, such as singular ``they'', ``their'', ``them'' (https://en.wikipedia.org/wiki/Singular_they), and so forth.

 10. 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.

 11. Please follow our code formatting rules, possibly running the etc/indent-code.el script to do that automatically for you (see Formatting Code).

When posting a patch to the mailing list, use [PATCH] ... as a subject.  You may use your email client or the git send-email command (see 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 NNN-done@debbugs.gnu.org.

Sending a Patch Series
----------------------

When sending a patch series (e.g., using git send-email), please first send one message to guix-patches@gnu.org, and then send subsequent patches to NNN@debbugs.gnu.org to make sure they are kept together.  See the Debbugs documentation (https://debbugs.gnu.org/Advanced.html) for more information.