search

whatwg / meta

Discussions and issues without a logical home
Creative Commons Zero v1.0 Universal
93 stars 159 forks source link

Main Git branch renaming across WHATWG repositories #174

Closed annevk closed 3 years ago

annevk commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

foolip commented 4 years ago

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

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 https://github.com/mheap/github-default-branch/issues/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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

foolip commented 4 years ago

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 commented 4 years ago

No, I haven't heard anything yet.

mheap commented 4 years ago

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 commented 4 years ago

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

foolip commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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:

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

There's also https://github.com/tabatkins/bikeshed/pull/1891, but I'm not sure if that's workable as those warnings are also for specifications outside the WHATWG presumably.

domenic commented 3 years ago

As pointed out in https://github.com/whatwg/streams/pull/1101#issuecomment-759772853, the grepping for "master" does not seem to be complete, i.e. it seems to have missed all the GitHub Actions code.

annevk commented 3 years ago

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 https://github.com/domenic/wattsi-server/issues/13, but it's unclear if that was related to the rename.

Thanks everyone!