Jason C. McDonaldWe were deciding what to rename our primary development branch...
The result: devel won! It will join fresh and stable as our triad of protected branches.
Today, we started the transition from master to devel. While many guides exist to explain how to rename master on your own repositories, this gets a little more complicated in a team.
Here's a few things you can do to make that transition easier.
Phase 0: Prepare
Make sure your team knows what's happening. Give them a few weeks notice. Explain your motivation for renaming master.
Seriously consider giving them a say in what the new primary branch should be. Cultural and historic issues aside, master was never a particularly insightful name, so take the occasion to find one the majority of your team actually likes! You can see some of our thoughts on four candidate names for the primary branch on the article mentioned above.
Set a date for the start of the transition. It's best if you pick a period somewhere towards the start of a development cycle, whatever that means to you, to limit disruption to workflow. Don't let the word "disruption" scare you off; chances are, this will go smoothly, but you still don't want to risk a hiccup a few days before something is supposed to ship to prod. ;)
Phase 1: Renaming
This is where you actually rename the branches! For this guide, I'll use devel for the new name, since that's what we picked, but you can substitute whatever name you prefer in there.
Here's the command for this, taken from this article by Alexis Moody, and adapted to our use:
git branch -m master devel
git push -u origin devel
Next, on your repository management tool — GitHub, GitLab, Bitbucket, Phabricator (in our case), or whatever) — set the new devel branch as the primary.
Do not yet delete master!!! This helps protect against initial bumps in the road:
- Developers can still pull from master.
- The CI/CD pipeline won't all break right away.
- It's extra insurance against data loss.
Instead, create a Git hook to block any changes pushed to master. This is a gentle way to transition your developers until they get into the new habit.
Now, go change your build pipeline. This part may or may not take a while.
Phase 2: Retraining
Instruct your developers to update their local copies, and give them time — say, a month? — to do it! Be sure to provide the commands to do so (see below).
That commit hook will prevent them from pushing to master out of habit, but the fact that master still exists (but not as the primary branch) will help smooth the transition.
To update a local copy to the new branch name, we're using the following code, based on this article by Scott Hanselman:
git checkout master
git branch -m master devel
git fetch
git branch --unset-upstream
git branch -u origin/devel
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/devel
At this point, you should also update your workflow documentation. If one or more of your team members has some extra bandwidth, consider asking them to undertake this. It will help them get into the habit of thinking of "devel" instead of "master".
During this time, builds should still be running, but on the new branch name (barring errors). Most issues with the changes to the CI/CD will resolve during this time.
Phase 3: Deleting master
After about a month, your team will likely have updated their workflows and habits, at least for the most part. You can now delete master on each of your repositories:
git push origin --delete master
Each of your developers can see the change by running the following on their local copies:
git fetch -p
Expect a few fresh issues with your CI/CD (there's always one typo, isn't there?), but most of those should be easy to iron out.
And, you're done! You have a shiny new primary branch with a useful name. What's further, you'll never have to do this again.
...or so we hope!
Okay, at least that's how it's supposed to go. We're through Phase 1 without any hiccups, but we'll be sure to update this post if there's anything else that comes up in the next month.
For us, master is set to be deleted on all our repositories on Monday, 03 August 2020! If there's any dramatic explosions of the build pipeline, we'll share the details on Twitter. :)
Is there anything you or your team has done to make this transition go smoother? Let us know in the comments!
WARNING: This is not the place to debate about whether master should be renamed. Any comments to that effect will be hidden and reported.
