[bug#76407,GCD] A better name for the default branch

  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
  

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

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

Thanks for writing this GCD up, I have other comments and thoughts, and
while I'm not against changing the branch name in principle my main
objection is this, I'm not sure we're technically ready (or at least in
a good state) to change the branch name for the default Guix channel.

> +  1. the `branch` field in `.guix-channel`;

This doesn't exist as far as I'm aware?

That record does have a url field, which is important as it means that
Guix can highlight when there is a mismatch between the URL being used
and the contents of the channel.

I think it's worth considering what a similar mechanism might look like
for branch names. Maybe Guix could have a notion of whether it's using
the "primary" branch for a channel (if you pull or time-machine to a
specific --branch, this is ignored), and that record could contain the
name of the primary branch, and then Guix could highlight when the two
differ.

That mechanism would allow for clearer messaging to users, since they
could see it again and again, rather than a news entry which would
usually only be shown once.

> (define-record-type* <channel> channel make-channel
>   channel?
>   (name      channel-name)
>   (url       channel-url)
>   (branch    channel-branch (default "master"))
>   (commit    channel-commit (default #f))
>   (introduction channel-introduction (default #f))
>   (location  channel-location
>              (default (current-source-location)) (innate)))

Is changing or removing the channel-branch default in the scope of this
GCD?

I'm in two minds about this. It's just the default, so it's trivial to
change it for the default channel. But ignoring it doesn't seem
consistent with the rest of the proposal.

Additionally, if the guix channel changes, then this might encourage
people managing other channels to make similar changes, and I think
there might be different and potentially more serious technical issues
with managing that change. I think it would be sensible to ensure
there's a good path for channels in general to change branch naming
before making the switch for the Guix channel.

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

In this scenario, assuming you're suggesting only pushing the news entry
related commits to "master", I think the branches diverging would be
problematic.

Assuming you're using the default channel configuration, if you pull to
one of these commits on "master", which isn't on the new master branch,
then I think the next time you go to pull, you'd hit the downgrade
protections (or at least you should do), since this is exactly the kind
of downgrade attack that it's trying to prevent against. You'd be
pulling a commit which isn't a descendant of the commit you're currently
on.

...

I also haven't even started to think about what implications this would
have for the services I'm involved with maintaining. The data service
instances and the bordeaux build coordinator all have current and
historic references to the "master" branch. In particular, the data
service goes beyond branches being pointers to commits and records the
state of branches over time.

It isn't immediately obvious to me how the data service could be adapted
to handle branches changing name to both capture that a branch may have
never actually pointed at a commit, but that commit is in the history of
the branch in the Git sense. I think with the current behaviour, we'd
have the history of the "master" branch (unless that's deleted), and
then separately the history for the new master (not "master") branch,
but that would start when that branch was cteated, and the two histories
would be separate from the view of the data service, and this
representation seems rather lacking.
  

Hi,

Am Mittwoch, dem 19.02.2025 um 17:21 +0000 schrieb Christopher Baines:
> > +  1. the `branch` field in `.guix-channel`;
> 
> This doesn't exist as far as I'm aware?
> 
> That record does have a url field, which is important as it means
> that Guix can highlight when there is a mismatch between the URL
> being used and the contents of the channel.
> 
> I think it's worth considering what a similar mechanism might look
> like for branch names. Maybe Guix could have a notion of whether it's
> using the "primary" branch for a channel (if you pull or time-machine
> to a specific --branch, this is ignored), and that record could
> contain the name of the primary branch, and then Guix could highlight
> when the two differ.
Nice catch.  I did copy the wording from the Codeberg GCD, which talks
about updating URL.  If `branch` is not considered by .guix-channel,
that's one field less to update.

> That mechanism would allow for clearer messaging to users, since they
> could see it again and again, rather than a news entry which would
> usually only be shown once.
> 
> > (define-record-type* <channel> channel make-channel
> >   channel?
> >   (name      channel-name)
> >   (url       channel-url)
> >   (branch    channel-branch (default "master"))
> >   (commit    channel-commit (default #f))
> >   (introduction channel-introduction (default #f))
> >   (location  channel-location
> >              (default (current-source-location)) (innate)))
> 
> Is changing or removing the channel-branch default in the scope of
> this GCD?
I think channel-branch should reflect the new default.

> I'm in two minds about this. It's just the default, so it's trivial
> to change it for the default channel. But ignoring it doesn't seem
> consistent with the rest of the proposal.
> 
> Additionally, if the guix channel changes, then this might encourage
> people managing other channels to make similar changes, and I think
> there might be different and potentially more serious technical
> issues with managing that change. I think it would be sensible to
> ensure there's a good path for channels in general to change branch
> naming before making the switch for the Guix channel.
Perhaps we could warn channel authors in advance that the default
branch is subject to change and ask them to set "branch" explicitly.

> > +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.
> 
> In this scenario, assuming you're suggesting only pushing the news
> entry related commits to "master", I think the branches diverging
> would be problematic.
The point here is that we don't have to keep master updated
indefinitely, but it should point towards a commit that is also on
main.  Denis 'GNUtoo' Carikli has another idea using symbolic
references.

> Assuming you're using the default channel configuration, if you pull
> to one of these commits on "master", which isn't on the new master
> branch, then I think the next time you go to pull, you'd hit the
> downgrade protections (or at least you should do), since this is
> exactly the kind of downgrade attack that it's trying to prevent
> against. You'd be pulling a commit which isn't a descendant of the
> commit you're currently on.
See above.

> ...
> 
> I also haven't even started to think about what implications this
> would have for the services I'm involved with maintaining. The data
> service instances and the bordeaux build coordinator all have current
> and historic references to the "master" branch. In particular, the
> data service goes beyond branches being pointers to commits and
> records the state of branches over time.
> 
> It isn't immediately obvious to me how the data service could be
> adapted to handle branches changing name to both capture that a
> branch may have never actually pointed at a commit, but that commit
> is in the history of the branch in the Git sense. I think with the
> current behaviour, we'd have the history of the "master" branch
> (unless that's deleted), and then separately the history for the new
> master (not "master") branch, but that would start when that branch
> was cteated, and the two histories would be separate from the view of
> the data service, and this representation seems rather lacking.
Good point, we should add a section talking about the Guix Data
Service.

Cheers
  

Hi Liliana,

A minor comment is to title: “Rename the default branch name“ or “Rename
from master to main”.  And not use word as “better”.

The rest is logistical stuff, FWIW.

On Tue, 18 Feb 2025 at 23:14, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:

> +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

Now, it’s submitted, I recommend to push this revision to a dedicated
branch, say ’wip-default-branch-name’ directly to the GCDs repository.

    https://git.savannah.gnu.org/cgit/guix/guix-consensus-documents.git

Well, I did but instead of pushing to it, I only pushed to my personal
copy of the repository:

    https://codeberg.org/zimoun/guix-consensus-documents/commits/branch/wip-default-branch-name

Feel free to just fetch and push if it appears to you fine.

Why?  Based on the experience of 001, it can quickly become a mess. :-)

There is several revisions in different emails and all becomes harder
and harder to follow.  Do I read the last revision?  This one?  And no
there is this yet another email?  And that MUA screwed up the subject…
etc.  Hard to follow; especially for the ones who just want to read the
last current revision.

Moreover, it’s more comfortable to read a plain file than a diff, IMHO.
For example, one revision of 001:

    https://git.savannah.gnu.org/cgit/guix/guix-consensus-documents.git/tree/0001-rfc-process.md?id=7da54b980efcd23ce662040b00712bd7fa76982e

(It perfectly works with Emacs browser EWW so it works for any browser. ;-))

Last, having all the revisions in a dedicated branch allows to easily
diff between each revision.

My 2 cents. :-)


> +SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-only

The recommendation is GFDL-1.3-no-invariants-or-later; see [1,2].  And I
think it would be better, no?  Maybe you have something specific in
mind?


1: https://git.savannah.gnu.org/cgit/guix/guix-consensus-documents.git/tree/000-template.md?id=c6a594ceb316e23bea975928eb2f40b7df450c94#n8
2: https://git.savannah.gnu.org/cgit/guix/guix-consensus-documents.git/tree/001-gcd-process.md?id=c6a594ceb316e23bea975928eb2f40b7df450c94#n8

Cheers,
simon
  

Am Donnerstag, dem 20.02.2025 um 18:25 +0100 schrieb Simon Tournier:
> Hi Liliana,
> 
> A minor comment is to title: “Rename the default branch name“ or
> “Rename from master to main”.  And not use word as “better”.
Okay.

> Now, it’s submitted, I recommend to push this revision to a dedicated
> branch, say ’wip-default-branch-name’ directly to the GCDs
> repository.
> […]
> Feel free to just fetch and push if it appears to you fine.
I fetched and updated; preserving history.


> > +SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-
> > only
> 
> The recommendation is GFDL-1.3-no-invariants-or-later; see [1,2]. 
> And I think it would be better, no?  Maybe you have something
> specific in mind?
Nah, I just copied one of the outdated templates D:

Cheers
  

Hi,

On Tue, 18 Feb 2025 at 23:14, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:

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

My current profile is:

        $ guix describe
        Generation 8	Sep 09 2024 15:14:29	(current)
          guix 056910e
            repository URL: https://git.savannah.gnu.org/git/guix.git
            commit: 056910ec864cb7cf3225a0c27679d94405db7dcd

And many people upgrade guix-daemon less than once a year. :-)

My point is: I’m not sure that a grace period of 30 days will be enough
considering the time to spread the word.  But, hey we need to bound
somewhere. :-)

Therefore, maybe we could imagine that the last commit pushed master
introduce a double pull.

Assume I still run this 056910e and we are after the grace period.  I
run “guix pull” so it fetch the last commit of master.  Now, when I run
again “guix pull”, I will get the last commit of main.  This second pull
could be transparent for me.

In other words, I still run this 056910e and we are after the grace
period, then when running “guix pull”, I automatically get the latest
up-to-date commit of main.  Obviously, I pay the unavoidable price of a
first pull but under the hood pull.

This might avoid: Oops why don’t I get the last?  Because you’re after
the grace period. :-)

I don’t know if my suggestion is worth.

Cheers,
simon
  

Hi

Am Freitag, dem 21.02.2025 um 19:16 +0100 schrieb Simon Tournier:
> My current profile is:
> 
>         $ guix describe
>         Generation 8    Sep 09 2024 15:14:29    (current)
>           guix 056910e
>             repository URL: https://git.savannah.gnu.org/git/guix.git
>             commit: 056910ec864cb7cf3225a0c27679d94405db7dcd
> 
> And many people upgrade guix-daemon less than once a year. :-)
> 
> My point is: I’m not sure that a grace period of 30 days will be
> enough considering the time to spread the word.  But, hey we need to
> bound somewhere. :-)
I put one month there as an optimistic estimate :)
We do have to talk about all the numbers used there as to whether they
are realistic, whether we should be keeping somethings for longer and
whether we can keep them for longer.

> Therefore, maybe we could imagine that the last commit pushed master
> introduce a double pull.
> 
> Assume I still run this 056910e and we are after the grace period.  I
> run “guix pull” so it fetch the last commit of master.  Now, when I
> run again “guix pull”, I will get the last commit of main.  This
> second pull could be transparent for me.
I don't think we should do this for two reasons:

First, the "double pull" commit would be introduced to master only,
which would break authentication of the main branch pulled this way.
Second, we would have to break Guix itself to introduce arbitrary code
execution for this particular code 😉

Perhaps instead, we can on the Git side "redirect" the master branch to
main.  This would avoid the double pull, and it would be truly
transparent.  Perhaps the following sequence of commands would achieve
just that.  (CC'ing Denis for their expertise)

Am Mittwoch, dem 19.02.2025 um 02:12 +0100 schrieb Denis 'GNUtoo'
Carikli:
> $ git checkout origin/master -b temporary
> $ git push origin HEAD:main
> $ ssh root@server
> $ cd /path/to/repository.git
> $ git symbolic-ref HEAD refs/heads/main # Change the main branch
> $ git symbolic-ref refs/heads/master refs/heads/main # Make master
> point to main

> This might avoid: Oops why don’t I get the last?  Because you’re
> after the grace period. :-)
> 
> I don’t know if my suggestion is worth.
Fair point.  Double-pulling is a source of annoyance in other package
managers, so we should do our best not to make it affect too many
users.

Cheers
  

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Therefore, maybe we could imagine that the last commit pushed master
> introduce a double pull.

I believe I understand what it's trying to achieve (and believe it is
worthwhile), but I struggled to understand how this would be technically
achieved.  Could you please share the technical details of this specific
part?
  

Hi Liliana,

Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:

> +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).

Consider this scenario: I have a machine that I upgrade once every two
months.  By the time the switchover is done, my machine still has
‘master’ in its ‘%default-guix-channel’ in its Guix.  Thus, when I run
‘guix pull’, I’ll end up pulling ‘master’, which (the GCD does not
clarify this) will either fail because the branch has been removed
altogether, or will give me an old snapshot.

Thus, I think the GCD should propose to keep updating the ‘master’
branch as a mirror of ‘main’ for, say, a year (a cron job can take care
of that).

Also, instead of changing the ‘branch’ field, I would suggest adopting
and finalizing <https://issues.guix.gnu.org/49252> and leaving ‘branch’
unset so that the server-side default branch is taken.

>+## Choice of branch name

I’m not convinced this section is necessary.  :-)

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

I don’t think this has to be simultaneous: both changes bring the
potential for breakage if we’re not careful enough, but it’s probably
best to deal with a single class of breakage at a time.

Also, perhaps clarify that this GCD is valid whether or not GCD 002 is
adopted.

Apart from that, it LGTM!

Ludo’.
  

Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:

> +  1. the `branch` field in `.guix-channel`;

I just realized: there’s no ‘branch’ field in ‘.guix-channel’.

Ludo’.
  

Hi Ludo’,

Am Sonntag, dem 23.02.2025 um 15:42 +0100 schrieb Ludovic Courtès:
> Hi Liliana,
> 
> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
> 
> > +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).
> 
> Consider this scenario: I have a machine that I upgrade once every
> two months.  By the time the switchover is done, my machine still has
> ‘master’ in its ‘%default-guix-channel’ in its Guix.  Thus, when I
> run ‘guix pull’, I’ll end up pulling ‘master’, which (the GCD does
> not clarify this) will either fail because the branch has been
> removed altogether, or will give me an old snapshot.
Actually, the GCD does specify this:

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

> Thus, I think the GCD should propose to keep updating the ‘master’
> branch as a mirror of ‘main’ for, say, a year (a cron job can take
> care of that).
Fair enough.  Keeping it updated for one year and then phasing it out
should give folks more time to adopt.

> Also, instead of changing the ‘branch’ field, I would suggest
> adopting and finalizing <https://issues.guix.gnu.org/49252> and
> leaving ‘branch’ unset so that the server-side default branch is
> taken.
SGTM.

> > +## Choice of branch name
> 
> I’m not convinced this section is necessary.  :-)
How do we achieve consensus on the proposed name itself, then?

> > +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.
> 
> I don’t think this has to be simultaneous: both changes bring the
> potential for breakage if we’re not careful enough, but it’s probably
> best to deal with a single class of breakage at a time.
Perhaps I am missing something crucial here, but IIUC most breakages
would result from the same record; with just one field between them. 
Since most configuration ends up being "fire and forget", reducing the
number of times they need to be edited sounds like a benefit to me.

> Also, perhaps clarify that this GCD is valid whether or not GCD 002
> is adopted.
Sure.

Cheers
  

Hello,

Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:

> Actually, the GCD does specify this:

Oh right, sorry.

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

Perfect!  Since the notion of major/minor release is fuzzy in Guix, I’d
suggest something like:

  2. two or more releases were made in the meantime.

>> > +## Choice of branch name
>> 
>> I’m not convinced this section is necessary.  :-)
> How do we achieve consensus on the proposed name itself, then?

‘main’ is an established and non-controversial name in this context,
which is why I thought we could omit the section.  It’s no big deal
though, we can keep it too.

>> I don’t think this has to be simultaneous: both changes bring the
>> potential for breakage if we’re not careful enough, but it’s probably
>> best to deal with a single class of breakage at a time.
> Perhaps I am missing something crucial here, but IIUC most breakages
> would result from the same record; with just one field between them. 
> Since most configuration ends up being "fire and forget", reducing the
> number of times they need to be edited sounds like a benefit to me.

Hmm yes, maybe you’re right.  The wording says “possibly simultaneous
change” so that leaves room.

Thanks,
Ludo’.
  

On Tue, Feb 18, 2025 at 5:24 PM Liliana Marie Prikler
<liliana.prikler@gmail.com> wrote:
>
> 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 :)

Thank you for this submission.

I have yet to meet someone taking passive offense at the "master"
branch but I do purposely mispronounce Guix from the project's
pejorative. Perhaps I can offer that as a future GCD.

And if we are to be offended, why whitewash history? We live
privileged lives in the most privileged nations during the most
privileged time in history. This is not the default state of the
world, to die of old-age peacefully in one's sleep. All of our peoples
were slaves, and all were slavers. More Europeans were trafficked to
Africa in the Barbary slave trade than Africans to America in the
North Atlantic slave trade. Only one of those two peoples survives.

Can we find greater but narrower consensus around the practical
motivation that 1) most users leave unchanged the git default "main",
therefore "master" will become increasingly uncommon and unexpected,
2) the choice of "main" is masterfully similar when tab-completing or
looking through a sorted list of refs, and 3) the move to Codeberg
presents a hopefully rare opportunity combine disruptive changes? We
do not need a comprehensive motivation if we can find consensus on the
outcome.

Greg
  

Liliana Marie Prikler <liliana.prikler@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
  

Hello,

Am Montag, dem 24.02.2025 um 23:07 +0100 schrieb Ludovic Courtès:
> Perfect!  Since the notion of major/minor release is fuzzy in Guix,
> I’d suggest something like:
> 
>   2. two or more releases were made in the meantime.
Adopted.

I also extended the grace periods to allow daemon idling for longer,
and added a section regarding other channels.

Cheers
  

Hi Liliana,

On Fri, 21 Feb 2025 at 20:56, Liliana Marie Prikler <liliana.prikler@gmail.com> wrote:

>> Therefore, maybe we could imagine that the last commit pushed master
>> introduce a double pull.
>> 
>> Assume I still run this 056910e and we are after the grace period.  I
>> run “guix pull” so it fetch the last commit of master.  Now, when I
>> run again “guix pull”, I will get the last commit of main.  This
>> second pull could be transparent for me.
>
> I don't think we should do this for two reasons:
>
> First, the "double pull" commit would be introduced to master only,
> which would break authentication of the main branch pulled this way.

At this end of the grace period, you have a direct path from the HEAD of
’main’ to the authenticated commit.  And you also have a direct path
from the HEAD of ’master’ to the authenticated commit.

Assuming, this commit with “double pull” lives only in ’master’ and
’master’ forks from ’main’ – fork because it holds the very commit.

I do not know the detail about switching from an authenticable branch to
another authenticable branch.  Because indeed, the HEAD of both branches
’main’ and ’master’ would not be in the same closure.

Hum, something I need to check for my understanding. :-)

> Second, we would have to break Guix itself to introduce arbitrary code
> execution for this particular code 😉

Why?  We only need to introduce a special case in
’update-cached-checkout’, no?

Somehow, we would have:

        * main
        | * master
        |/
        * End grace period

so we could have something like introduced in the ’master’ branch.

--8<---------------cut here---------------start------------->8---
1 file changed, 1 insertion(+), 1 deletion(-)
guix/git.scm | 2 +-

modified   guix/git.scm
@@ -653,7 +653,7 @@ (define* (update-cached-checkout url
                                                #:cleanup-period
                                                %checkout-cache-cleanup-period)))
 
-       (values cache-directory (oid->string oid) relation)))))
+       (update-cached-checkout ... #:ref `(branch . "main") ...)))))
 
 (define* (latest-repository-commit store url
                                    #:key
--8<---------------cut here---------------end--------------->8---

Well, modulo the former question about authentication. :-)

> Perhaps instead, we can on the Git side "redirect" the master branch to
> main.  This would avoid the double pull, and it would be truly
> transparent.  Perhaps the following sequence of commands would achieve
> just that.  (CC'ing Denis for their expertise)

Yeah, who can more can less. :-)

> Am Mittwoch, dem 19.02.2025 um 02:12 +0100 schrieb Denis 'GNUtoo'
> Carikli:
>> $ git checkout origin/master -b temporary
>> $ git push origin HEAD:main
>> $ ssh root@server
>> $ cd /path/to/repository.git
>> $ git symbolic-ref HEAD refs/heads/main # Change the main branch
>> $ git symbolic-ref refs/heads/master refs/heads/main # Make master
>> point to main
>
>> This might avoid: Oops why don’t I get the last?  Because you’re
>> after the grace period. :-)
>> 
>> I don’t know if my suggestion is worth.
>
> Fair point.  Double-pulling is a source of annoyance in other package
> managers, so we should do our best not to make it affect too many
> users.

Assuming we are allowed to do that on the server hosting the Git
repository.

Cheers,
simon
  

Hi,

On Sun, 23 Feb 2025 at 15:42, Ludovic Courtès <ludo@gnu.org> wrote:

> Consider this scenario: I have a machine that I upgrade once every two
> months.  By the time the switchover is done, my machine still has
> ‘master’ in its ‘%default-guix-channel’ in its Guix.  Thus, when I run
> ‘guix pull’, I’ll end up pulling ‘master’, which (the GCD does not
> clarify this) will either fail because the branch has been removed
> altogether, or will give me an old snapshot.

After the end of the grace period, I propose to introduce a commit, thus
to have master as a fork of main, and such commit would teach
’update-cached-checkout’ to automatically switch.

The only question is about dealing with authentication; well it requires
a special care.  But it appears to me doable since both master and main
would be authenticated.

> Thus, I think the GCD should propose to keep updating the ‘master’
> branch as a mirror of ‘main’ for, say, a year (a cron job can take care
> of that).

Even one year isn’t enough. ;-)  I’m not sure to run “guix pull” once a
year as root.  And many irregular users will have an old snapshot.

Just to me mention that new issues are still reported about v1.2.0
released…  Sorry I’m too old to remember such ancient time. ;-)


Cheers,
simon
  

Hi Tomas,

On Sun, 02 Mar 2025 at 17:51, Tomas Volf <~@wolfsden.cz> wrote:

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

[...]

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

Since this appears to me the premise for the rest, let be sure we have
this premise. :-)

1. Can you live with “main” as the branch name?
   Or cannot you live with it?

2. The same question for these people.

Let me share my opinion, FWIW.  When discussing such topics where I
don’t really feel personally concerned, I refrain to ask myself if it is
founded or not – slippery slope –, and instead, I try to focus on what
the change costs me and I ask to myself if I can or if cannot live with
this change.

Somehow, whatever if I consider the rename deeply ridiculous or highly
important or something in the middle, instead I answer: Ok, it costs me
nothing and I can live with this rename.  Then I scrutinize the details
using the same frame. :-)

Cheers,
simon