Package: guix-patches;
Reported by: Liliana Marie Prikler <liliana.prikler <at> gmail.com>
Date: Tue, 18 Feb 2025 22:07:02 UTC
Severity: normal
View this message in rfc822 format
From: Tomas Volf <~@wolfsden.cz> To: Liliana Marie Prikler <liliana.prikler <at> gmail.com> Cc: 76407 <at> debbugs.gnu.org Subject: [bug#76407] [GCD] A better name for the default branch Date: Sun, 02 Mar 2025 17:51:59 +0100
[Message part 1 (text/plain, inline)]
Liliana Marie Prikler <liliana.prikler <at> gmail.com> writes:
> Hi Guix,
>
> this patch introduces GCD 003 “A better name for the default branch”.
> I've taken the comments on guix-devel into account (most of them anyway)
> and updated the document accordingly. Note that references to GCD 002
> are made. That GCD was drafted earlier, but may or may not already be
> submitted by the time you read this. Do be patient :)
>
> Cheers
>
> ---
> 003-better-default-branch-name.md | 187 ++++++++++++++++++++++++++++++
> 1 file changed, 187 insertions(+)
> create mode 100644 003-better-default-branch-name.md
>
> diff --git a/003-better-default-branch-name.md b/003-better-default-branch-name.md
> new file mode 100644
> index 0000000..95952a5
> --- /dev/null
> +++ b/003-better-default-branch-name.md
> @@ -0,0 +1,187 @@
> +title: A better name for the default branch
> +id: 003
> +status: submitted
> +discussion: https://issues.guix.gnu.org/76407
> +authors: Liliana Marie Prikler
> +sponsors: Simon Tournier, Ian Eure, Vagrant Cascadian, Ludovic Courtès
> +date: 2025-02-18
> +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
> +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.
Was there any study or statistics about this topic?
The two black people I have asked consider the whole "master -> main"
branch rename ridiculous, and me, descendant of people after who the
Slavery institute is named (Slavs), also do not care. So I am curious
whether there are any hard data on this topic.
> +
> +# 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”.
Since this GCD is all about feelings, let me point out that some people
do have negative feelings about the "main" as well. It is a politically
charged name, so I am not sure it satisfies the goal of "Guix
contributors, as a whole, feel comfortable with".
> +
> +- 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,
I like this one.
> + albeit one that is not clearly defined (are the other branches
> + not guix as well?)
But other branches are not Guix. If someone tells me "pull the latest
Guix", I would assume that means master branch (or whatever the new name
would be). I do not think anyone would go to the conclusion "oh, latest
Guix must mean rust-team branch, because it is also a Guix".
In my eyes other branches are not Guix, they are what Guix can become
one day.
> +
> +- 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” 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) 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 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.
Just to make sure, the "update" here refers to syncing the master branch
to what main is? So the histories would not diverge, it is just the
master would be behind. Is that correct?
> The `master` branch may keep following
> +the `main` branch for a grace period of 30 days anyways.
> +
> +Even after the `master` branch no longer syncs up to main, it may be
> +important to still have it pointing at some commit. Old installation
> +media, handcrafted `channels.scm`, external documentation and scripts
> +may all still be referring to the `master` branch even long after the
> +rename (see also Cost of Reverting below). To ensure that these do
> +not fail immediately, the old branch shall not be deleted until
Is there a reason to delete it at all? It will not be prominently
displayed anywhere, it would not be updated anymore, so is there any
harm (even to those people who would supposedly get offended by the
current branch name) if it just stays there? Only place where it would
be visible is listing all remote branches, which seems... acceptable?
Having it will allow even old setups to update, at the cost of double
pull.
Or, pushing bit further, is there a reason to not keep it updated? So
that people just can pick branch they feel the most comfortable with?
> +
> +1. at least one year has passed since this GCD has been accepted, AND
> +2. enough Guix releases have been made in the meantime, meaning
> + a. at least one major release, OR
> + b. at least three minor releases.
Given our current release cadence, this basically means the branch stays
forever, so you just as well may say so.
One thing I am not sure about are Guix packages in distributions. For
example, I do not know whether Debian would update Guix to new version
in already released version. So if Trixie is released with current
1.4.0, and we than make a 3 minor releases and delete the master branch,
will Debian users still be able to pull? (I think we have Debian
developer taking care of Guix here on the list, so maybe he can chime
in.)
Not sure what other distributions package Guix, and whether you care
about them in general.
> +
> +## 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.
I am not sure how this plays together with the timeline set above ("14
days after acceptance of this GCD at the earliest, and 30 days at the
latest."). What if this GCD is voted on before the GCD 002? Would it
not make sense to rephrase it to something like "14 days after
acceptance of this GCD or 14 days after result of vote on GCD 002,
whichever happens later"?
> +
> +The repository update path in this GCD is only valid as long as 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.
These two paragraphs above seem to have no connection to "Cost of
Reverting".
> +
> +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
One drawback that is missing here is the impact on scripting and tools
that people have on their machines. I have at least few scripts that
operate with origin/master that will need to be updated. I would not be
surprised if various crons that break will keep being discovered for
weeks or months after the rename.
It is valid to consider that an acceptable cost, but I think the general
fallout across the ecosystem should be recognized in this document, and
clearly declared as acceptable.
> +
> +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.
In that case time spent debating this GCD and doing all the work it
would cause, would maybe be better spent on some outreach programs
and/or workshops for less fortunate people?
> 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.
Have a nice day,
Tomas
--
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.
[signature.asc (application/pgp-signature, inline)]
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.