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 git@github.com: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 follow these additional instructions after GitHub is updated.

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

Zuul-CI

If the collection has been setup as a project in Ansible Zuul you will follow a slightly modified process instead of the above.

Create the new branch and push it to GitHub:

git clone git@github.com: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 follow these additional instructions after GitHub is updated.

Branch settings on GitHub will then be managed via gitops in the project-config repo. You need to add a default-branch setting to the collection's configuration in two places.

git clone https://github.com/ansible/project-config
cd project-config
github/projects.yaml:
 - project: ansible-collections/amazon.aws
   description: Ansible Collection for Amazon AWS
+  default-branch: main
   options:
     - has-projects

zuul.d/projects.yaml:
 - project:
     name: github.com/ansible-collections/amazon.aws
+    default-branch: main
     merge-mode: squash-merge
     templates:
       - system-required

Update Open PRs

• 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

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 )