Equitable Code:
Retiring
master on GitHub
By Andrew Ring
Member of the Nines Technical Staff


July 3, 2020

Introduction

At Nines we iterate constantly when building tools for our radiology practice. In this post we'll talk about updating some of the common infrastructure used throughout the software industry.


In recent years, there has begun a movement to remove terms master and slave from software systems. In 2018, Python removed many references for version 3.8. More recently, GitHub has announced they will be changing the default branch from master to main.


Traditionally, the canonical branch used in git repositories is named master. It is the default branch created in new repositories, and is frequently subject to stronger protections by requiring peer review of code changes, as well as Continuous Integration (CI) testing.


At Nines, we have already made this change. I wanted to share some of my thoughts on the topic, as well as a guide to make this transition as easy as possible for others.

Why remove references to master?

The word master can serve as a trigger for thoughts about slavery, racism, and systemic injustice. Many point out that in this context, the use is analogous to a master record in the recording industry, i.e., the authoritative version. While that may be the case, it’s beside the point. These sorts of subtle, but frequent, triggers are known as microaggressions. They are common, and generally used without an intent to harm. They might sound small, but cumulatively, they have a big effect. This type of issue is pervasive enough that AI makes the effects very clear. The pain caused is real, and we can easily help. All it takes is attention, and action.

I’m in, now what?

Great! Before we begin Nines’ 9-step process, make sure you have admin access to the GitHub repository you are updating. You should be able to see the Settings tab within the repository:

1.  Communicate Upcoming Changes

It’s important to communicate the process with any developers who are also using your repository. It’s best to pick a time to transition when there isn’t a high amount of activity with the repository, if possible, as Pull Requests merged at the wrong time could result in lost information.


Example:

In line with a wider movement, I am renaming the default branch in <repository> from master to main. There will be a small planned downtime where PRs should not be merged, on <date> from 8 am to 9 am. Please let me know if you have any concerns about this process. </date></repository>

2.  Creating New Branch

Creating a new branch in git is very simple. From a local clone of your repository, checkout the master branch and make sure you are up to date with GitHub:


git checkout master
git pull


Create the new branch from your updated base:


git checkout -b main

Now push the new branch up to GitHub:

git push --set-upstream origin main

It’s important to note here that all previous commit history is retained in this process.

3.  Update Branch Protection

Frequently, the primary branch will be subject to a variety of branch protection rules. This will appear in GitHub Branch Settings as something like this:


At this stage, we can expand the rule to cover both master and main branches using a wildcard. Click Edit on the rule, and update the Branch name pattern to be ma*. It’s important to note that the “Applies to n branches” box does not update until changes are saved. This should end up looking something like:


4.  Update Code and Documentation

Next search through your repository for explicit inclusion of master. Frequently, this will include CI/CD configuration files, and possibly other scripts and tooling. This needs to be done with some care, as there may be many other uses of the word, such as other repositories, or unrelated code.



Your IDE of choice likely has a good way to search through all of the files in your repository. If you don’t have something like this, here is a simple script to print all occurrences:


git ls-files | xargs -I {} sh -c 'echo "<<< {} >>>" && grep -ni master {}'

Don’t forget to check for any new changes in master which might need to be merged into main as well. You can check for these by selecting the main branch in the Code tab, and clicking compare.


5.  Update Default Branch

Now we’ll update GitHub to treat main as the default branch. This will cause Pull Requests to default to using main as the base, will change which branch is shown by default in the Code tab, etc. This is changed in the Settings tab, under Branches:


6.  Update Open Pull Requests

When master is deleted, any open Pull Requests which use it as a base will be automatically closed, and cannot be reopened. To avoid this, any open Pull Requests should have their base updated to main. The base is listed at the top of the Pull Request like this:



Clicking Edit in the upper right corner will change the base into a dropdown. Update it and Save.

7.  Update Branch Protection, part 2

In order to delete master, we need to first need to remove the branch protection that still applies to it. This is much like the previous change, but now replace ma* with main.

8.  Delete master From GitHub

With branch protection removed, deleting the branch from origin (GitHub) is as simple as:

git push -d origin master

9.  Communicate Changes and Local Cleanup

Now it’s time to close the loop and communicate the completion of the developers. In addition to confirming the work is complete, there is some minor clean up to do on each developer’s machines, to remove copies of the deleted master branch. This can be done by running this in each clone:


git fetch
git checkout --track origin/main
git branch -d master


Example:

The transition in <repository> from master to main is now complete. All open Pull Requests have been updated to reflect this. As a final step, please run the following in your local copy of <repository> to remove outdated metadata:</repository></repository>

git fetch && git checkout --track origin/main && git branch -d master

Done!

I hope this made the process of updating your branch simple and relatively painless. Thank you for helping to make our world, and industry, a little bit more welcoming.


General Inquiries

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.