Proposal: migrate ProGit2 default branch from `master` to `main`

[HonkingGoose]

Outdated information

Migrating the branch name is way easier now, GitHub does most of the work, and anybody holding old links will get redirected to the proper branch automatically.

Consider the information listed on this issue badly outdated. Use at your own risk.

---

GitHub will automate parts of the migration later this year:

Moving to the main branch as the default branch will be made easier for existing repositories, later this year: https://github.com/github/renaming#later-this-year-seamless-move-for-existing-repositories-

The changes made by GitHub will fix the following issues that moving on our own now would create:

• Open pull requests need to be re-targeted to the new branch
• Draft releases need to be re-targeted to the new branch
• Warning users who fetch/clone from our repository to use the new branch name, and help with migration by creating documentation.

So I would strongly suggest, that we wait until GitHub has fixed those issues, this will help with the load on the maintainers of this project, and increase the likelihood of a successful move.

We still need to manually fix certain things, whether we move manually now, or let GitHub automate parts of the process later.

Preparation:

• Check with the translation projects if they are up for this move.
• I've asked the Git-SCM project how this change would impact them at Impact on the git-scm site if ProGit2 English book changes default branch from master to main? git/git-scm.com#1501. They've merged prefer HEAD to master in update tasks git/git-scm.com#1502 so they use HEAD instead of master for their update tasks. It should just work now.
• Check the moving over checklist, figure out if more is needed?
• Go/no go decision.
• Decide on a "move over" date, and communicate it to the community via a pinned issue on GitHub.
• Pin the "move over" issue, so that it stays on the top of the "Issues" tab in GitHub.
• Write documentation on "How to change your branch from main to master as a contributor" and pin it with a Issue, and put it in the README.md.

Moving over:

• Merge pull-request Changes to move from master to main as our default branch #1464 to:

• Change the tag_on_master script to use main instead of master.
• Rename tag_on_master script to tag_on_main.
• Ensure travis.yml uses the renamed tag_on_main script.
• Ensure travis.yml uses the main branch for its tests.
• Change the reference to master to main in atlas.json
• Change a link in the translation documentation.
• Change a link in the bug report template.

• Create a main branch, and push it to the repository.
• Copy the branch protection policies that are used on master to the new main branch.
• Change the default branch from master to main on the repository settings page.
• Re-target open pull-requests, this can be done manually by the pull owner, by going to the pull-request, and clicking on edit, and select the main branch as target for the pull. Or we can wait until GitHub has automated this.
• Dependabot will migrate its own pulls to the new default branch automatically.
• Confirm that any changes to the ProGit2 book that come after the branch name change are reflected on the git-scm website after 24 hours. (They run a nightly build with the ProGit2 changes.)
• Finally after ensuring everything still works, delete the master branch on the remote.

Benefits/drawbacks of proposal:

Benefits:

• The project will be more inclusive to people who are bothered by the master slave connotation.
• Give a good example on how to move a project over, so that other projects know the move can be done.

Drawbacks:

• There are currently 1600 forks/clones at least of this repository, including the translation projects, each of those will have to do some work after the move.
• The maintainers of the ProGit2 project will be quite busy with merging/closing pull-requests prior to the move. This will not be necessary if we wait until GitHub makes things easier later this year...
• There's a chance that we miss changing/updating something prior to the move, and we break something.

Related issues:

#1462

Further info:

More info and guidance from GitHub on moving a repo from master to main can be found at GitHub's official renaming repo.

---

Edits:

I've removed a previously listed drawback (breaking the old links to files on master, as it's fixed by GitHub already...

Links to deleted branches now redirect to the default branch

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

[HonkingGoose]

Hi @ben,

This is just me thinking "out loud" on the steps that would be needed, and on the benefits/drawbacks.

If you don't want to move from master to main you can close the issue. 😄
If you do decide to make the move, I'll help by making some pull-requests and issues to guide the process.

Greetings,

HonkingGoose

[HonkingGoose]

Hi @ben, I've just tried the full migration at a test repo: https://github.com/HonkingGoose/migration-test-progit2 and have tested most of the migration. Apart from the release flow which I can't test yet, everything kept functioning.

I don't know how to duplicate your secrets handling for GitHub and Travis CI: There are 3 ways according to GitHub, and Travis has some way of handling secrets too, I think. It would be nice to have a duplicated setup, so that I can test the release script migration as well. 👍

Test flow:

I used this adapted checklist: https://github.com/HonkingGoose/migration-test-progit2/issues/4

1. Duplicate the entire ProGit2 repository into a new testing repo, default branch is master as it is with your repo
2. Setup Travis CI but without the releases on GitHub script secret tokens working.
3. Setup branch protection rule for master: require status checks to pass.
4. Merge migration pull into master, with the changes I have prepared for the real deal: https://github.com/HonkingGoose/migration-test-progit2/pull/2
5. Go to my local workstation and git pull master so that I have the migrated scripts.
6. git branch -m master main on the local workstation.
7. Do git push --set-upstream origin main
8. Go to the GitHub branch protection settings, copy setting from master to the main branch.
9. Set default branch from master to main in the GitHub repo settings.
10. Re-target https://github.com/HonkingGoose/migration-test-progit2/pull/3 from master to main as pull request owner
11. Merge re-targeted pull request, Travis CI will pass.
12. The Dependabot update for Asciidoctor 2.0.10 was automatically re-targeted when the default branch was changed: https://github.com/HonkingGoose/migration-test-progit2/pull/1
13. Travis CI build is still working on main, but I do not know if the release script works, as this cannot be tested yet by me!

What I learned from this:

• Dependabot will re-target its pull requests automatically. 🚀
• Re-targeting a exisiting pull request can be done manually by the pull owner in a simple way. (I do not know if you as administrator have rights to re-target a pull request...).

I hope this is helpful.

HonkingGoose

[HonkingGoose]

Hi @ben, it seems that GitHub are going to roll out some updates in January 2021 to make migration to main easier.

You can get a preview of their plans here in the github/renaming README:

https://github.com/github/renaming#creating-a-seamless-move-for-existing-repositories-

[HonkingGoose]

We don't need all the cruft from up top anymore, it's way easier to change the branch name now.

See PR #1669 for the manual changes, and ignore the checklists I made above, as they are outdated.