GNU bug report logs - #76407
[GCD] A better name for the default branch

Previous Next

Full log

View this message in rfc822 format

From: Christopher Baines <mail <at> cbaines.net>
To: 76407 <at> debbugs.gnu.org
Cc: Liliana Marie Prikler <liliana.prikler <at> gmail.com>
Subject: [bug#76407] [GCD] A better name for the default branch
Date: Wed, 19 Feb 2025 17:21:39 +0000

[Message part 1 (text/plain, inline)]

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

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.