Previous: , Up: Contributing   [Contents][Index]


7.5 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. When sending a patch series, 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, for more information.

Please write commit logs in the ChangeLog format (see Change Logs in 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. Take some time to provide an adequate synopsis and description for the package. See Synopses and Descriptions, for some guidelines.
  2. 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).
  3. Make sure the package builds on your platform, using guix build package.
  4. 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.

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

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

  8. When writing documentation, please use gender-neutral wording when referring to people, such as singular “they”, “their”, “them”, and so forth.
  9. 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.

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


Previous: , Up: Contributing   [Contents][Index]