Submitting Patches (GNU Guix Reference Manual)

22.10 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 (see Submitting patches to a project in Git User Manual). Contributors are encouraged to take a moment to set some Git repository options (see Configuring Git) first, which can improve the readability of patches. Seasoned Guix developers may also want to look at the section on commit access (see Commit Access).

This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (see Tracking Bugs and Changes). 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 ISSUE_NUMBER@debbugs.gnu.org, where ISSUE_NUMBER is the tracking number (see Sending a Patch Series).

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

You can help make the review process more efficient, and increase the chance that your patch will be reviewed quickly, by describing the context of your patch and the impact you expect it to have. For example, if your patch is fixing something that is broken, describe the problem and how your patch fixes it. Tell us how you have tested your patch. Will users of the code changed by your patch have to adjust their workflow at all? If so, tell us how. In general, try to imagine what questions a reviewer will ask, and answer those questions in advance.

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

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.
Take some time to provide an adequate synopsis and description for the package. See Synopses and Descriptions, for some guidelines.
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).
Run guix style package to format the new package definition according to the project’s conventions (see Invoking guix style).
Make sure the package builds on your platform, using guix build package. Also build at least its direct dependents with guix build --dependents=1 package (see guix build).
We recommend you also try building the package on other supported platforms. As you may not have access to actual hardware platforms, we recommend using the qemu-binfmt-service-type to emulate them. In order to enable it, add the virtualization service module and the following service to the list of services in your operating-system configuration:
```
(service qemu-binfmt-service-type
 (qemu-binfmt-configuration
   (platforms (lookup-qemu-platforms "arm" "aarch64"))))
```
Then reconfigure your system.

You can then build packages for different platforms by specifying the --system option. For example, to build the "hello" package for the armhf or aarch64 architectures, you would run the following commands, respectively:
```
guix build --system=armhf-linux --rounds=2 hello
guix build --system=aarch64-linux --rounds=2 hello
```
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.
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. In particular, avoid adding texlive as a dependency: because of its extreme size, use texlive-updmap.cfg procedure instead.
Check that dependent packages (if applicable) are not affected by the change; guix refresh --list-dependent package will help you do that (see Invoking guix refresh).
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 bordeaux.guix.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.
When writing documentation, please use gender-neutral wording when referring to people, such as singular “they”, “their”, “them”, and so forth.
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.
Please follow our code formatting rules, possibly running guix style script to do that automatically for you (see Formatting Code).
When possible, use mirrors in the source URL (see Invoking guix download). Use reliable URLs, not generated ones. For instance, GitHub archives are not necessarily identical from one generation to the next, so in this case it’s often better to clone the repository. Don’t use the name field in the URL: it is not very useful and if the name changes, the URL will probably be wrong.
Check if Guix builds (see Building from Git) and address the warnings, especially those about use of undefined symbols.
Make sure your changes do not break Guix and simulate a guix pull with:
```
guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master
```

When posting a patch to the mailing list, use ‘[PATCH] …’ as a subject, if your patch is to be applied on a branch other than master, say core-updates, specify it in the subject like ‘[PATCH core-updates] …’.

You may use your email client, the git send-email command (see Sending a Patch Series) or the mumi send-email command (see Debbugs User Interfaces). 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.

Expect some delay when you submit your very first patch to guix-patches@gnu.org. You have to wait until you get an acknowledgement with the assigned tracking number. Future acknowledgements should not be delayed.

When a bug is resolved, please close the thread by sending an email to ISSUE_NUMBER-done@debbugs.gnu.org.