22.11.2 Managing Patches and Branches

Changes should be posted to guix-patches@gnu.org. This mailing list fills the patch-tracking database (see The Issue Tracker). It also allows patches to be picked up and tested by the quality assurance tooling; the result of that testing eventually shows up on the dashboard at ‘https://qa.guix.gnu.org/issue/ISSUE_NUMBER’, where ISSUE_NUMBER is the number assigned by the issue tracker. Leave time for a review, without committing anything.

As an exception, some changes considered “trivial” or “obvious” may be pushed directly to the master branch. This includes changes to fix typos and reverting commits that caused immediate problems. This is subject to being adjusted, allowing individuals to commit directly on non-controversial changes on parts they’re familiar with.

Changes which affect more than 300 dependent packages (see Invoking guix refresh) should first be pushed to a topic branch other than master; the set of changes should be consistent—e.g., “GNOME update”, “NumPy update”, etc. This allows for testing: the branch will automatically show up at ‘https://qa.guix.gnu.org/branch/branch’, with an indication of its build status on various platforms.

To help coordinate the merging of branches, you must create a new guix-patches issue each time you create a branch (see The Issue Tracker). The title of the issue requesting to merge a branch should have the following format:

Request for merging "name" branch

The QA infrastructure recognizes such issues and lists the merge requests on its main page. The following points apply to managing these branches:

1. The commits on the branch should be a combination of the patches relevant to the branch. Patches not related to the topic of the branch should go elsewhere.
2. Any changes that can be made on the master branch, should be made on the master branch. If a commit can be split to apply part of the changes on master, this is good to do.
3. It should be possible to re-create the branch by starting from master and applying the relevant patches.
4. Avoid merging master in to the branch. Prefer rebasing or re-creating the branch on top of an updated master revision.
5. Minimise the changes on master that are missing on the branch prior to merging the branch in to master. This means that the state of the branch better reflects the state of master should the branch be merged.
6. If you don’t have commit access, create the “Request for merging” issue and request that someone creates the branch. Include a list of issues/patches to include on the branch.

Normally branches will be merged in a “first come, first merged” manner, tracked through the guix-patches issues. If you agree on a different order with those involved, you can track this by updating which issues block⁴⁷ which other issues. Therefore, to know which branch is at the front of the queue, look for the oldest issue, or the issue that isn’t blocked by any other branch merges. An ordered list of branches with the open issues is available at https://qa.guix.gnu.org.

Once a branch is at the front of the queue, wait until sufficient time has passed for the build farms to have processed the changes, and for the necessary testing to have happened. For example, you can check ‘https://qa.guix.gnu.org/branch/branch’ to see information on some builds and substitute availability.

Once the branch has been merged, the issue should be closed and the branch deleted.

Sometimes, a branch may be a work in progress, for example for larger efforts such as updating the GNOME desktop. In these cases, the branch name should reflect this by having the ‘wip-’ prefix. The QA infrastructure will avoid building work-in-progress branches, so that the available resources can be better focused on building the branches that are ready to be merged. When the branch is no longer a work in progress, it should be renamed, with the ‘wip-’ prefix removed, and only then should the merge requests be created, as documented earlier.