July 3, 2020
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.
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.
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.
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:
Create the new branch from your updated base:
Now push the new branch up to GitHub:
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:
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:
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:
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>
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.