Proposal: renaming 'master' branch to 'main'

Tue Jan 17 08:02:23 UTC 2023

On Mon, Jan 16, 2023 at 02:55:10PM +0000, Daniel P. Berrangé wrote:
>I don't recall exactly when it first came up, but it has been a few years
>now since the idea of moving away from 'master' as the git default branch
>name became a topic in OSS communities. Far from the first mention:
>
>  https://sfconservancy.org/news/2020/jun/23/gitbranchname/
>
>Both gitlab.com and github.com now default to 'main' as the default
>branch when creating new repositories:
>
>  https://about.gitlab.com/blog/2021/03/10/new-git-default-branch-name/
>  https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/
>
>Some notable large open source projects have done, (or at least started)
>to rename the default branch in their existing projects too. eg
>
>  GNOME: https://gitlab.gnome.org/GNOME/glib/-/issues/2348
> Fedora: https://fedoraproject.org/wiki/Changes/GitRepos-master-to-main
>
>For libosinfo we did a rename last year. There was a little disruption
>but nothing too terrible, IIRC, missing weblate translation branch
>update was our main mistake.
>
>I'd suggest it is time to libvirt to get on this train and rename our
>default branch to 'main' in all repositories.
>
>There are essentially two options
>
>  * Rename 'master' to 'main'
>
>    With this, anyone pulling from an existing checkout will get an
>    error telling them that 'master' does not exist. It won't tell
>    them about 'main', but at least it gives them a sign that something
>    in their checkout probably needs changing.
>
>    Downside is that any URLs pointing to source files / commits with
>    a branch name in the URL will become 404s.
>
>  * Clone 'master' to 'main'
>
>    With this, anyone pulling from an existing checkout will get no
>    updates. It is very easy for people to not realize that they are
>    tracking a branch which is no longer used
>
>    Downside is also that the undesirable term 'master' remains
>    present in the repo, even if unused. We might also miss places
>    which still refer to 'master' which will end up outdated
>

We can also then remove everything from master and just keep a README
file explaining the situation.

>
>Ideally, we would rename 'master' to 'main', while the git server
>adds 'symbolic-ref' to effectively create a symlink to 'main'. This
>would mean anyone pulling from 'master' would get content from 'main'.
>AFAICT, this is not supported by gitlab.com though. I had held off
>suggesting the rename, hoping such support might arrive, but I'm
>doubting it will happen on a timescale to be useful, if at all.
>
>In terms of impact
>
>  * Developers need to checkout 'main' and delete their now stale
>    'master' branch
>
>  * Any open merge requests need updating, hitting 'Edit' and choose
>    the new 'main' as the target
>
>  * User repo forks may wish to delete their 'master' and push
>    'main', but that's entirely optional, since many people never
>    touch/look at the default branch in their forks.
>
>  * CI mostly shouldn't be impacted since we use CI_DEFAULT_BRANCH
>    most places instead of hardcoding 'master'. A few exceptions
>
>       - Links to artifacts include a branch name
>       - integration tests mention branch name
>       - References to check-doc/cirrus-run jobs use 'master'
>         as the docker tag
>
>  * GitHub mirroring won't track the rename, it'll just add 'main'
>    without removing 'master', so needs manual fixup.
>
>  * Need to update 'protected branch' and 'default branch' fields
>    in gitlab repo settings for each repo
>
>  * Weblate needs updating to translate from 'main' instead of
>    'master'
>

Any custom tooling (local) needs updates too, I've done mine already
last year to accomodate for both branch names.

>So the rename isn't free of cost, but it should all be one-time
>only costs, which I think is something we can live with. Given
>our never ceasing development stream there's not really any
>'right' time todo such a change. Just after a release is probably
>as good as it gets, and January is marginally better since we skip
>Feb and have a 6 week gap until the March 1st release.
>

If you include the time left for people to notice (time_of_change -
time_of_announcement) then we can give people more time after another
release, but it would probably end up being the same time.

No objections from me for either of the options above.

Godspeed,
Martin

>With regards,
>Daniel
>-- 
>|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
>|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
>|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20230117/9af2e4e3/attachment.sig>