Rename master branch to main

[paulmelnikow]

There's a recent movement to replace "master" with a word that is descriptive while being absent the racist history of master & slave. This isn't a new idea, however it's gaining momentum on Twitter given the groundswell of action in the United States and globally after the police killing of George Floyd in Minneapolis two weeks ago. I stand with the protestors. 🖤

The language we use matters. Changing this for the Shields-managed repos is a minor inconvenience for us, and mostly a one-time thing, and seems well worth it.

I'd propose we rename the branch in Shields to main, update the open PRs to target that, and identify whatever else we have to update, like the deploy bot, deploy scripts, badges, etc.

There's a tool here we could use for the PRs: https://github.com/ethomson/retarget_prs

(I think we should also review the places where we default to master in the badge code, and think about how to handle that, however let's discuss that in #4755 and open new issues as necessary.)

[calebcartwright]

Thanks for bringing this up! I'm a big +1 on making this change

[chris48s]

There is a practical consideration here.

First of all, lets assume that the shields.io repo default branch would be renamed from master to main but our application will continue to assume that the default branch on most git(hub) repos is called master for now. That can move to another issue. For now, it is an accurate assumption.

We frequently use badges/shields either as an example or in a service test for a badge that makes the assumption your default badge is called master, or explicitly using the branch name master. If we no longer have a master branch, there's going to be a whole load of service tests that fail or examples that don't work at the point the change is made. In order to make this change, we would need to first replace all places where badges/shields is used in a service test or example with the assumption (implicit or explicit) that a branch which is called master exists.

To be clear, I'm not opposing this change, but there is a bunch of stuff that would need to happen first to do it in an orderly way.

Other (less cumbersome) things that would need updating in order to make this change (do add more if you think of them):

• Impact on CI/coverage setup
• Heroku deploy process/Makefile
• Any badges in use in READMEs
• Documentation references (esp links)
• dependabot config/GH auto-approve action

[calebcartwright]

but our application will continue to assume that the default branch on most git(hub) repos is called master for now. That can move to another issue. For now, it is an accurate assumption

Agreed. I don't think we can change that unless and until GitHub changes the name the platform selects for default branch.

I believe another item we'll need to update is the message/badge added by the shields-deplyoment bot since I believe that's doing a comparison of master and gh-pages

[chris48s]

Agreed. I don't think we can change that unless and until GitHub changes the name the platform selects for default branch

I think this is a big and complicated issue, so I decided to write a small novel on the topic. Lets discuss that independently in #5215

[chris48s]

Turns out this is actually going to happen the other way round
We'll still need to remove the explicit references to badges/shields/master in tests/examples, but default branch tests will continue to work, so that's good..

[calebcartwright]

AFAIK GitHub doesn't support renaming an existing branch, so I think we'd need to create a new main branch and change that to the repo's default. Assuming I've got that right, another thing we may also want to consider is the timeframe for removing the the original master branch from the repository altogether after changing the default.

Hopefully, no one is consuming assets directly from the source repo (i.e. consuming badge-maker via git instead of the npmjs package) but I suppose they could be and have the same master branch assumption we had within Shields that could break.

Perhaps we could pick and post a date for when the master branch would be removed altogether?

[paulmelnikow]

Hopefully, no one is consuming assets directly from the source repo (i.e. consuming badge-maker via git instead of the npmjs package) but I suppose they could be and have the same master branch assumption we had within Shields that could break.

If they are doing this for some reason, and not specifying the branch, they will continue to get the default branch.

[chris48s]

Some additional useful reading on this:

• https://github.com/github/renaming/
• https://github.blog/changelog/2020-07-17-links-to-deleted-branches-now-redirect-to-the-default-branch/

Current recommendation from GH is:

If you haven’t moved yet, we recommend not moving right now, and waiting until later this year. We’re investing in tools to make the renaming the default branch of an existing repository a seamless experience for both maintainers and contributors.

[chris48s]

https://github.blog/changelog/2020-08-26-set-the-default-branch-for-newly-created-repositories/

[chris48s]

Github have now released their tooling to make this easier
https://github.com/github/renaming#rename-existing
I think this is probably the easiest it is going to get.

[calebcartwright]

I think this is probably the easiest it is going to get.

Agreed. Shall we pick a target date for making the change? I feel like we've done enough forewarning about the intended change so as to not catch anyone off guard (still a bit unclear as to how branch changes were breaking certain direct-repo consumption patterns in other projects, but wanted to be mindful of it anyway)

[chris48s]

I think I'd rather frame it as "We need to do these things and then we can change it. Now is a good time to start doing them." rather than "We will change it on date X regardless of whether we have done the things or not.", but it is good to have a date to aim for :)

Most of this falls into the category of "get busy with grep" but I think the tasks we need to get done to support this are going to include:

• Update references to our master branch in any service tests that use badges/shields for integration testing e.g:

  • shields/services/github/github-checks-status.tester.js

    Line 7 in d69f7b6

    .get('/badges/shields/master.json')

  • shields/services/dynamic/dynamic-json.tester.js

    Line 37 in fcf6678

    '.json?url=https://github.com/badges/shields/raw/master/package.json&query=$.name'

• Update references to our master branch on any badges that use badges/shields as an example repo e.g:

  • shields/services/github/github-commit-status.service.js

    Lines 24 to 26 in fcf6678

    	user: 'badges',
    	repo: 'shields',
    	branch: 'master',

• Go through the documentation and find/update any documentation with internal links that use master e.g:

  • shields/dangerfile.js

    Line 87 in 3a23695

    '[guidance](https://github.com/badges/shields/blob/master/doc/logos.md#contributing-logos) ',

  • https://github.com/badges/shields/blob/46b98c40be47b823a41746ca2caa39bc276702a2/doc/code-walkthrough.md
    This includes:
  • markdown docs
  • JSDocs
  • Other code comments
  • the "help" text in badge popups
  • anything else I'm forgetting here?

• Update any CI/repo automations that reference master e.g:

  • shields/.github/workflows/deploy-docs.yml

    Line 5 in a93e6a3

    - master

  • shields/.circleci/config.yml

    Line 308 in e1bd160

    - master

    
    This includes:
  • dependabot
  • GH actions
  • Circle CI
  • anything else I'm forgetting here?

• Update the badges at the top of our own README

• Look at external services that the GH repo integrates with directly - do we need to change any config via their web UIs? This includes:

  • Heorku
  • Circle CI
  • DockerHub
  • Coveralls
  • LGTM
  • anything else I'm forgetting here?

• Content in other repos that might reference our master branch I suspect there are mercifully few of these, but maybe:

  • https://github.com/badges/daily-tests
  • https://github.com/chris48s/approve-bot
  • Anything else I'm forgetting here?

• Update our branch protection rule(s)

I've tried to be comprehensive there but please shout if you can see things I have not thought of. Lets try and make the list as comprehensive as possible before we start so we understand the full scope of the problem.

Obviously that is quite cumbersome to co-ordinate. Redirects will paper over the cracks if we overlook or ignore some of that stuff (e.g: links in docs) but there are definitely important things in there we do need to manually deal with. Also if there are any of those categories of that Github pixies will take care of for us (e.g: branch protection rules), lets identify them so we know we don't have to do it/can check GH has worked the appropriate magic. I think we should probably aim to have a PR (or several smaller PRs) reviewed and ready to merge at the point we make the change and co-ordinate: merging those PRs, changing the actual branch name on the repo, and making the necessary updates to external services/repos as close together as possible to try and minimise the problems.

[calebcartwright]

I think I'd rather frame it as "We need to do these things and then we can change it. Now is a good time to start doing them." rather than "We will change it on date X regardless of whether we have done the things or not."

Agreed, didn't intend to imply the latter, though also admit that in reading your list there were definitely a few things I hadn't considered so thanks for pulling all these together 👍

Do you think we need to create separate issues for addressing some of the specific or could we just check them off inline here?

For example, there's a few of these line items that can be resolved independently and don't have to be done as part of a big bang, such as the changing the service tests and examples to use a different repository target/or a different non-master branch in our repo, we could (potentially) go ahead and plugin -main as a target branch in CI configs and defer removing -master to a later date, etc. Would separate issues for those types of things be beneficial?

[chris48s]

I think it is going to be simpler if there are fewer things that all need to happen all at the same time so if we can break this down and identify tasks that we can do ahead of time in a "forwards-compatible" way that will be helpful.

[chris48s]

I set up a couple of test repos
On this one https://github.com/chris48s/master-to-main-test1 I set master as the default branch but also pushed one called main. Then I switched the default branch from master to main
On this one https://github.com/chris48s/master-to-main-test2 I set master as the default branch but didn't push one called main. Then I renamed master to main.

Only the second one (the one where I renamed the branch rather than switching it) I got his notification:

So I think this means that in order to get the features noted in https://github.com/github/renaming#rename-existing I think we have to rename our master to main. If we set up a main branch and switch all the tests/examples to use that and then switch the default branch then we don't get those nice things :(

[calebcartwright]

So I think this means that in order to get the features noted in https://github.com/github/renaming#rename-existing I think we have to rename our master to main. If we set up a main branch and switch all the tests/examples to use that and then switch the default branch then we don't get those nice things :(

Were we still considering the alternative? I was under the impression that we were definitely going to leverage GitHub's rename feature.

If we're going to preemptively change test targets/examples from the master branch in our own repo to something else, I was thinking we'd change the target altogether (e.g. from badges/shields/master to some other foo/bar/branch)

[chris48s]

Were we still considering the alternative? I was under the impression that we were definitely going to leverage GitHub's rename feature.

Until I tested it, I wasn't sure that switching the default branch to another existing one didn't trigger the same behaviour as renaming.

If we're going to preemptively change test targets/examples from the master branch in our own repo to something else, I was thinking we'd change the target altogether (e.g. from badges/shields/master to some other foo/bar/branch)

Yeah I think we do need to do that 👍

[calebcartwright]

Gotcha, makes sense now