Rename the default branch

by Liliana Marie Prikler — Sun 04 May 2025
sponsored by Simon Tournier, Ian Eure, Vagrant Cascadian, Ludovic Courtès

Timeline

15 February
drafting18 February
discussion21 April
deliberation05 May
withdrawn

Summary

Currently, much of Guix's development takes place on the “master” branch. This name is neither particularly meaningful nor inclusive; choosing to use it may inadvertently alienate potential contributors. To mitigate these effects, we should more clearly communicate, what the default branch is all about.

Motivation

It is well known, that Git works with whatever branch name one chooses. However, for historical reasons, the default/initial/main branch for development used to be “master” — particularly in 2012, when the first commit to Guix was made.

Recent versions of Git support arbitrary initial branches and the default branch name is subject to change upstream, at least in part because the current default — “master” — may be perceived as harmful. While the intended meaning is something close to “an original, from which copies are made”, there are several other meanings of the word that spring to mind more easily, some of have a racist or sexist connotation.

One goal of the Guix community is to foster a healthy community around the software we use. Using clear language that does not pertain to harmful stereotypes is a key towards achieving this goal. Thus, as a proactive step, we should rename the default branch.

Detailed Design

This section explains the chosen solution among the available options, the scope of the proposed migration, and a migration path.

Scope of this document

This document discusses only to change the name of the default branch, not to change the branching strategy. Such ideas, e.g. to have a “stable” branch containing only bug-fixes and well-tested features and an “unstable” or “experimental” branch would need to be discussed in a separate document.

Choice of branch name

In this section, we discuss potential branch names that have been considered. The goal is to find a name that Guix contributors, as a whole, feel comfortable with.

While this GCD is still being reviewed, new suggestions may be added, and benefits and drawbacks for each name discussed. Once this GCD is accepted, these benefits and drawbacks shall be shortly summarized, and a final decision with a short justification as the one at the end of this section shall be the last paragraph of this section.

• The currently used “master” has more than ten different meanings, some of them pertaining to slavery, others to dominance, and yet others merely to skill and expertise. It is understandable that some contributors would feel uncomfortable with this name, given that not all uses are equally frequent.

• The currently proposed alternative “main” has several meanings relating to “importance”, the most obvious being “most important”.

• Other alternatives would be “trunk” as a visual metaphor from which “branches” spawn, and “base” with the same meaning.

• “guix” being the name of the project also serves as an option, albeit one that is not clearly defined (are the other branches not guix as well?)

• Similar to “guix”, “development” merely signifies that some sort of development happens on the branch; a fact that should hold for most, if not all branches.

We choose “main” because it is currently the explicit initial branch for a git checkout as per git-fetch in (guix build git) as well as the default branch for a number of Guix-adjacent projects such as Shepherd. Another name could be chosen by any means that support achieving a consensus, e.g. comments on this GCD or a popular vote.

Manual Updates

Sections 19 (Security Updates) and 22 (Contributing) of the Guix manual would need to be reworded to reflect the new default branch. Other sections mentioning “master” branches may be reworded at any time regardless of this GCD. Some mentions of the word “master” are tied to particular services and thus subject to rewording only once upstream adopts a different terminology.

Repository Update Path

For a complete list of repositories associated with the Guix project, see GCD 002 ‘Migrating repositories, issues, and patches to Codeberg’. Most repositories can rename their default branch with no issue (see also Cost of Reverting below).

For Guix itself, we would decide on a flag day 14 days after acceptance of this GCD at the earliest, and 30 days at the latest. On that day, the official branch of the Guix repository would become "main". This flag day is only about the canonical Guix channel; see the next section for other channels.

After this switch, committers will have to push exclusively to the main branch. The "master" branch will become a mirror of the main branch, with a script periodically updating it for at least one year after the switch, as a way to ease migration to the new branch for users.

A commit would reflect that by updating:

1. the branch field of %default-guix-channel in (guix channels);
2. any other reference to the "master" branch of the Guix repository that may appear in the repository (in particular the Manual Updates above).

Following this commit, an entry in etc/news.scm would explain the migration, accompanied by a blog post on https://guix.gnu.org/en/blog/.

On other channels

In a separate commit, the default branch field of the <channel> record type shall be updated as well. The new default value depends on whether https://issues.guix.gnu.org/49252 or not. If HEAD can be used, it shall be used so as to not force other channels into any particular naming scheme. Assuming this change is transparent, no further action is required; the change can simply be announced in the same news entry and blog post mentioned in the Repository Update Path.

If HEAD can not be used freely by the flag day or the change to it would be intransparent, a separate news entry and blog post shall announce that the default will be changed from "master" to "main"; as well as point out how to keep one's channel working after this change. This change should be communicated in advance, so that smaller channels are given ample time to adapt.

Continuous Integration

The jobset for the master branch would be removed and a jobset for the main branch with the highest priority and the same set of architectures would be created.

Relation to other Guix Consensus Documents

Since this change has the potential to affect users and contributors in ways that will disrupt their workflow for some amount of time as they reconfigure their local checkouts to point at the new branch, it should best be adopted as the same time as other, similar changes. In particular, an adoption at the same time as GCD 002 ‘Migrating repositories, issues, and patches to Codeberg’ is desirable; however, both documents may be accepted regardless of the other.

The repository update path in this GCD assumes that it is simultaneously upheld by other, similar GCDs. Again GCD 002 ‘Migrating repositories, issues, and patches to Codeberg’ needs to be considered as a possibly simultaneous change. For the sake of clarity, the promises made in the repository update path w.r.t. the availability of the old branch shall not exceed those of any other accepted GCD and instead be updated to match.

Cost of Reverting

This change mostly affects contributors, who would have to run the following command once to pull from (and in the case of committers push to) the new main branch:

$ git branch --set-upstream-to <origin>/main

Users of the guix CLI would be advised to run guix pull again to fetch the latest commit from the main branch. Users of old installation media (e.g. disk images for version 1.4.0) would continue to use the "master" branch and the default channel URL of said installation media until they run guix pull. A new release may mitigate this annoyance somewhat.

The main branch may be renamed to any other name (including "master") by repeating the steps laid out in the Repository Update Path and Continuous Integration above, using <name> instead of "main".

Drawbacks and Open Issues

There is an ongoing political debate as to whether the name “master”, standing alone, should be considered harmful. Similar debates may well surround other names given enough time and particular circumstances. More generally, as language continues to evolve, meanings that appear obvious today may no longer remain so in the future.

It is unclear, what effect, if any, the name of the default branch has to contributor satisfaction. The choice of a name may well appear similar to choosing the colour of a bikeshed. What constitutes a meaningful branch name will inevitably be a matter of opinion.

Voting Summary - 04-05-2025

Voting pool: last new Team member added on April 14th 2025 [^1] Voting tally: gcd003-20250504-voting-record.rec

Member voting:

Observer declarations:

Voting result:

• 45% (22 votes) voted to pass the GCD
• 14% voted to disapprove
• 41% abstained by not voting

Following the GCD process [^2], this GCD is withdrawn as it didn't achieve consensus. It may be presented againt to members following further efforts to achieve consensus.

Voting notes and links

[^1]: from git log -p etc/teams.scm

[^2]: GCD 001 specifies that "The GCD is accepted if (1) at least 25% of all team members–as of the start of the “Deliberation Period”–send a reply, and (2) no one disapproves. In other cases, the GCD is withdrawn"