[GCD] Rename “main” branch

[Liliana Marie Prikler]

title: Rename "main" branch
id: 003
status: draft
discussion: https://issues.guix.gnu.org/<number assigned by issue tracker>
authors: Liliana Marie Prikler
sponsors:
date: <date when the discussion period starts>
SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-only
---

# 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 “main” 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.  In the 
meantime,
Guix adopted a Contributor Covenant, pledging to interact in ways that
contribute to an open, welcoming, diverse, inclusive and healthy community.
Hence, as a proactive step, we should choose a default branch that reflects
the vision the Guix project has for the kind of development that takes place
on this branch.

# Detailed Design

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

## Choice of branch name

Several options exist, such as “main”, “trunk”, “base”, 
“development”,
“stable”, “unstable” and the currently-used “master”.  The 
important part
is that Guix contributors, as a whole, should be able to agree on one such
name and feel comfortable with it.  The name “master” does not fulfil this
requirement.

The names “main”, “trunk” and “base” are comparatively neutral 
options.
- “main” is a little more abstract and signifies that the branch is the
   most important one,
- “trunk” and “base” serve as a visual metaphor to signify that a large
  chunk of development takes place there.

“stable” and “unstable” may be chosen if a decision is made that certain
stability guarantees are to be upheld on particular branches.  These require
greater changes to our branching strategy and are thus outside the scope
of this GCD.

Finally, “development” is a loose qualifier stating that development takes
place.  As development happens also e.g. on team branches, this name may not
be that fitting.

We choose “main” simply because it is currently the explicit initial branch
for a git checkout as per `git-fetch` in `(guix build git)`.  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) would need to be reworded
to reflect the new main 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 main 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 main development branch would become "main".
A commit would reflect that by updating:

  1. the `branch` field in `.guix-channel`;
  2. the `branch` field of `%default-guix-channel` in `(guix channels)`;
  3. 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.  The `master` branch would then point at the commit of said
news entry, and would need to be updated only after said news are
translated into another language.  The `master` branch may keep following
the `main` branch for a grace period of 30 days anyways.

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

## Timing in Accordance with 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.

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

It is unclear, what effect, if any, the name of the main 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.