Changing the git default branch to main

This is just a scratchpad for now to hold the experiences of those who have made this transition

• https://github.com/ansible/community/wiki/Changing-the-git-default-branch-to-main
  • @abadger Verified and integrated into the instructions below
• https://twitter.com/xunit/status/1269881005877256192
  • @abadger Verified and integrated into the instructions below
• https://github.com/abadger/antsibull/pull/1
  • @abadger Verified and integrated into the instructions below

Potential instructions

Please update this section with any tested steps that are either simpler or handle more cornercases

Update the repository on GitHub

Create the new branch and push it to GitHub:

git clone [email protected]:organization/repo
cd repo
git branch -m master main   # Move the master branch to the main branch locally
git push -u origin main   # Set the origin to track upstream's main branch

Once this is done, the clone in the repo/ directory will have the main branch. Other local clones will need to use git

In the GitHub settings:

• Go to GitHub settings and set the default branch to main via https://github.com/ansible-collections/REPONAME/settings/branches

  • GitHub instructions on changing the default branch.

• Go to GitHub settings and change any branch protection rules for master to be for main instead. via via https://github.com/ansible-collections/REPONAME/settings/branches. If rules don't exist, create them:

  • Include administrators: Enabled
  • Require linear history: Enabled

• Go to GitHub and retarget the open PRs from master to main

  • A basic script that works: https://gist.github.com/jillr/3ea18312c5cef54ef07c47e8a180de6c
  • If there's a small number of PRs, this could be done manually instead. The API to change pr base branches https://developer.github.com/changes/2016-08-23-change-base/ in case you need to extend the script.

• Go to GitHub and delete the master branch via https://github.com/ansible-collections/REPONAME/branches

• Update any config that references the master branch. For instance, continuous integration configuration and deployment scripts may hardcode the branch name. An example for one project: https://github.com/ansible-community/antsibull/pull/100

Updating Shippable

(For Repos that use Shippable)

• Ensure the master branch no longer exists
• https://app.shippable.com/github/ansible-collections/REPONAME/settings
  • Synchronize SCMs: Click Sync and wait
  • Refresh page
  • VIEW SETTINGS/Display Branches: Ensure main is shown and master isn't.

Updating codecov

• https://codecov.io/gh/ansible-collections/REPONAME/settings
  • Default Branch: main then click update

GitHub Actions

Nothing Required

Zuul-CI

FIXME: Various things needed?

Updating a fork on GitHub

Someone please verify

If you have forked a repository on GitHub, you need to follow the same steps as for the main project's GitHub git repo in order to use main as well. This is less critical as you are less likely to have PRs against your fork but it still does nice things like defaults to main for the working copy when you clone a fresh local copy rather than defaulting to the obsolete and non-updated master branch.

Updating local clones

The fresh clone you made in the Github section will now be using main but what if you have other clones (or other contributors need to sync with your changes to the canonical repository)?

git checkout master
git branch -m master main
git fetch
git branch --unset-upstream
git branch -u origin/main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

(from https://twitter.com/xunit/status/1269881005877256192 )