Featured on Dr. Dobb’s, this is the second blog in a three part series about making the switch to Git in the enterprise. In the first post, we discussed why so many teams today have decided to make the switch. This post focuses on the technical aspects of how Atlassian actually made the switch to Git.
In this three part blog series I will focus on the biggest migration Atlassian has done – migrating the 11-year-old Jira codebase from SVN to Git. What obstacles did we encounter? What lessons did we learn? And most importantly, how did we do it without sacrificing active development on Jira? We hope that sharing this experience helps anyone approaching a similar migration.
We’ll focus on Git, because Jira moved to Git, but everything in this series applies equally to Mercurial. At Atlassian, we use both.
Migration – The Technical Side
Stably migrating is daunting but it is not brain surgery; there is a process we’ve employed to make it manageable.
1. Clone your repository to Git
First, choose a location for your Git repository. When we migrated Jira, we decided to move from an internally hosted SVN repository to a private Bitbucket repository in the cloud. This was a good fit for us – we have geographically disparate teams in Sydney, Gdansk and San Francisco; plus it makes committing easy for people working from home. It’s also part of our internal “eat-your-own-dogfood” practice to run off Bitbucket since that’s our DVCS code-hosting product. We also mirror our repository to Atlassian Stash (again, for “dogfood” purposes), our behind-the-firewall Git repository manager. That said, this guide works for any Git repository, regardless of how or where it’s hosted.
Now that you have a shiny new home for your code, you can move in. (Don’t forget to provide plenty of pizza & beer for everyone.) And because it’s best to lift with your legs, not your back, we recommend cloning your SVN repository into Git using git-svn clone:
Essentially you’ll want to git-svn clone to create an intermediate repository on a local machine (which might be your desktop or some shared machine – we used a nearby wallboard machine), then push from this intermediate Git repository to the ‘real’ Git host you will be using. All infrastructure and developers will be reading and writing to this “real” Git host, not the intermediate repository.
This is the most technical part of the migration; a whole article could be written on this alone. In fact, Stefan Saasen (Development Lead on Atlassian Stash) has put together an excellent guide to this.
2. Mirror from SVN to Git
After your migration is complete (Jira’s initial git-svn clone took three days to run), setup a script to mirror every commit to SVN into Git. I’ve shared a version of the script we used here.
Our advice is to make the Git repository read-only to everyone except the user that the mirroring script runs under. If you have eager developers who start committing directly to the Git repository, the mirroring script might encounter merge conflicts and you’ll will have to manually resolve them. Avoid this at all costs.
At this stage of the migration, every developer is still committing to SVN and all your infrastructure is still reading off SVN.
3. Move your infrastructure
The next stage is to iteratively cut over your infrastructure from SVN to Git:
This step takes the bulk of the time. Iteratively cut over and test each piece of infrastructure. Our particular steps were:
- Change code reviews to point at the Git repository. Fisheye/Crucible (our Web-based code review software) made it easy to add a repository in any version control system. Developers started creating code reviews against Git, which was their first exposure of the actual Git repository; then
- Clone a couple of CI builds to run from the Git repository, side-by-side with an SVN build.
We let these two big changes soak and dealt with any issues while we continued with other technical changes, including:
- Updating our release process;
- Updating our source distribution. We release the source code with each Jira release, so we changed this process to release source from the Git repository;
- Build versions. The footer on each Jira page displays the version that’s running – this needed to be converted to a Git hash; and
- Internal tooling. Jira has an update script that checks if any submodules need to be recompiled when you update from the repository.
This approach allows you to roll back any single change without affecting the entire migration. At the end of this step, all of your infrastructure will be running off Git, while your developers will still be committing to SVN.
By the time we were ready to cut over, we had let all the above changes soak for more than a week and had fixed a number of issues. Once your team decides to cut over from SVN to Git, they must ensure that they are at a point where the cost of rolling forward through any issues is manageable.
4. Cut over
When all infrastructure has moved, you are ready for the final cutover, where developers commit to Git not SVN.
Some advice here:
- Broadcast the date of this change loudly, clearly and widely across your organisation;
- At the given time, make your SVN repository read-only. If developers make commits to SVN after the cut-over is complete, it will cause you untold pain to manually merge those commits to the Git repository;
- Once you have made your SVN repository read-only, run your mirroring script one last time to pick up the last few commits; and
- For each migration at Atlassian, we’ve always chosen to leave the read-only SVN repository running. This keeps anything from breaking that may be pointing at something in SVN – e.g., a link to an SVN revision number in a code review, or a very old branch of code that builds from source.
Congratulations! You are now running off Git.
Migration – The Human Side
So you might know that you can run a pretty slick migration from the technical side, minimize commit downtime and ensure high availability of your supporting infrastructure. But are your developers ready for the change? In the next part of this blog series we will discuss the human side of making the switch to Git.
Want more Git resources?
You can keep your current workflow style while migrating your team to Git. Learn more about migrating from SVN with our online Git resources.
