Proposal: renaming 'master' branch to 'main'

[Daniel P. Berrangé]

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


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'

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.

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