Main Git branch renaming across WHATWG repositories

[annevk]

As per https://mail.gnome.org/archives/desktop-devel-list/2019-May/msg00066.html the use of master in Git is clearly problematic.

I have some hope that GitHub will make this easier soonish (see https://twitter.com/natfriedman/status/1271253144442253312 though note that the replies are trash).

If that doesn't pan out, we can do it ourselves per the instructions in https://www.hanselman.com/blog/EasilyRenameYourGitDefaultBranchFromMasterToMain.aspx. main is also the name I'd suggest we use as there seems to be some tentative agreement around that.

Does anyone foresee any problems?

[dbaron]

One GitHub issue I'm aware of is that if a repository is using GitHub Pages, that's only possible from a branch called master or gh-pages. So if any are, they'd probably need their primary branch renamed to gh-pages instead of main, at least for now. I saw a tweet about 6-12 hours ago saying they're working on fixing that, but I can't find it again.

I think another is that the step to update the default branch in the article you cite causes GitHub to give a big red warning box saying it might break certain things; I don't remember the contents of the warning but I think one of them was currently-outstanding pull requests. Another might be clones that people have. Given the convention about maintaining relatively long-lived PRs, that might be a bit problematic, and it's probably worth seeing how bad the effects will be with a test in another repository...

[zcorpan]

I saw this, which might be helpful: https://github.com/mheap/github-default-branch (via https://twitter.com/mheap/status/1272277332783497218?s=20 )

[foolip]

I tried renaming the default branch on a personal repository today to see what I'd run into:

• Created and pushed the main branch
• Pushed an additional commit to the main branch fixing CI setup
• Changed the branch protection rules to apply to the main branch
• Changed the default branch in GitHub's settings
  • This step automatically changed the base branch of the single open PR, a nice surprise
• Removed the master branch

This all is not hard to do across all of our repos.

However, the final step of removing the master branch is going to break URLs, and there are probably quite many. I filed mheap/github-default-branch#6 about this, but don't know a good solution. The least bad option I can see is to add a final commit to the master branch with an ALL CAPS commit message and changing the README or another file that's unlikely to be linked, explaining the situation. The branch would need to be left around in perpetuity.

To solve this well, GitHub-side handling of branch renaming by redirecting would be needed.

Something I haven't explored is what happens to local checkouts. This too won't be entirely smooth unless there's GitHub-side handling, some kind of aliasing.

[domenic]

To solve this well, GitHub-side handling of branch renaming by redirecting would be needed.

I am hopeful this is in the works, given a vague public statements from the GitHub CEO on Twitter. So we should probably hold off to see what they announce.

[zcorpan]

https://github.com/chancancode/branch-rename might also be helpful.

I agree that waiting for GitHub is reasonable, but we can also inform them about the redirect feature request. Is Contact GitHub the right venue?

[foolip]

Yeah, use that form. I tried to email support@github.com a few days ago (about something else) and that doesn't work. Unlike what I've seen people claim, I've found GitHub's support to be pretty great, just not always fast.

[zcorpan]

Done, I've sent this:

See https://github.com/whatwg/meta/issues/174#issuecomment-644423829

> To solve this well, GitHub-side handling of branch renaming by redirecting would be needed.

Also see https://github.com/mheap/github-default-branch/issues/6

Can GitHub provide a way to redirect URLs when renaming branches?

[zcorpan]

Hello Simon,

Thanks for writing in! We are actively working alongside the Git project itself, as well as other version control vendors, on making three changes in GitHub: (1) we are changing the default branch name for new repos away from ‘master’ (2) we are making it easy for users to choose their own default branch name for all new repos created (3) we are releasing guidance and tools for users who may choose to rename their default branch in existing repos.

Our Pages team is also exploring ways to resolve the issue of the limited branch options in Pages sources.

I'm afraid I can't provide more concrete details yet, but thank you for writing in with this feedback. I am going to pass along your suggestion of redirecting URLs to our Product team, as that would certainly fall under number 2 above.

[annevk]

You might want to point out that it falls under 3.

[foolip]

https://github.com/google/mirror-branch-action by @jyasskin is something we could consider here, and fairly trivial to roll out using https://github.com/whatwg/spec-factory. Or we bake something into our deploy scripts to avoid using extra CI resources for this.

My only hesitation is that by maintaining the branch like this, "master" will keep showing up in git fetch and git log --decorate output indefinitely, so it'll still be there staring maintainers and contributors in the face every day.

Has anyone heard any updates on what GitHub might be planning here?

[travisleithead]

No, I haven't heard anything yet.

[mheap]

Good news! GitHub have just announced that any deleted branches now redirect to the default branch https://github.blog/changelog/2020-07-17-links-to-deleted-branches-now-redirect-to-the-default-branch/

[annevk]

Note that later in the year this will be a mostly automated process: https://github.com/github/renaming.

[foolip]

https://github.blog/changelog/2020-07-17-links-to-deleted-branches-now-redirect-to-the-default-branch/ is excellent!

https://github.com/github/renaming#later-this-year-seamless-move-for-existing-repositories- looks like it will add some convenience, but I think most of the work for us would be in adapting our CI setup and updating references to master in lots of little places.

In other words, I don't think we necessarily need to wait for more support in https://github.com/github/renaming.

[annevk]

I looked into this again and per https://github.com/github/renaming#creating-a-seamless-move-for-existing-repositories- we should be able to roll this out soon. I suspect there will be some announcement in the coming weeks and when that comes we can start with the transition.

When that time comes we should grep for master as we do have code, e.g., https://github.com/whatwg/meta/blob/master/review.py, that relies on that. Some of that might continue to work as a result of GitHub making things more seamless, but we should still clean it up. Given that there are cross-repository dependencies we probably need to do it all in one sweep. Once GitHub makes the announcement I'm happy to start preparing PRs for the changes we need to make to code and such. And I guess I can work with @foolip (if he agrees) on doing the renaming and ensuring things work as expected afterward.

If anyone has other things we should consider now would be a good time to voice them.

[annevk]

There's two kinds of changes we need to make. For all repositories we need to flip the branch name. We can also do this for archived repositories by unarchiving them, changing it, then archiving them again. (I have not listed those for now, but I'd like to do that as well once the main work is done.)

Here are the repositories in a list, I've already flipped some that I deemed safe:

• books
• compat
• console
• dom
• encoding
• fetch
• figures
• fullscreen
• html
• html-build
• infra
• loader
• meta
• mimesniff
• misc-server
• notifications
• participant-data
• participate.whatwg.org
• platform.html5.org
• quirks
• sg
• spec-factory
• storage
• streams
• url
• wattsi
• web-history
• whatwg.org
• xhr

Then we need to make code changes to account for the branch name changes, let's track those in this list (thought to be complete):

• Meta: default branch rename compat#139
• Meta: default branch rename console#192
• Meta: default branch rename dom#943
• Meta: default branch rename encoding#251
• Meta: default branch rename fetch#1139
• Meta: default branch rename fullscreen#189
• Meta: default branch rename html#6285
• Default branch rename html-build#259
• Meta: default branch rename infra#355
• Default branch rename #197
• Meta: default branch rename mimesniff#137
• Default branch rename misc-server#142
• Meta: default branch rename notifications#163
• Default branch rename participate.whatwg.org#154
• Default branch rename platform.html5.org#58
• Meta: default branch rename quirks#55
• Default branch rename sg#151
• Default branch rename spec-factory#25
• Meta: default branch rename storage#118
• Meta: default branch rename streams#1101 and Streams: update link in README web-platform-tests/wpt#27182
• Meta: default branch rename url#572
• Default branch rename wattsi#140
• Default branch rename whatwg.org#349
• Meta: default branch rename xhr#307

There's also speced/bikeshed#1891, but I'm not sure if that's workable as those warnings are also for specifications outside the WHATWG presumably.

[annevk]

This is now done, including for archived repositories. To avoid the mistake I almost made for your own projects, use

grep -r master * .* --exclude-dir={..,.,.git}

or equivalent.

Pull requests will need to be rebased unfortunately due to the build configuration files including the default branch name. Let me know if you encounter problems.

The only weirdness I encountered thus far has been whatwg/build.whatwg.org#13, but it's unclear if that was related to the rename.

Thanks everyone!