At this stage of the migration, every developer is still committing to SVN and 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:

Figure 3: Beginning cutting over operations to GIt.

We iteratively cut over and tested each piece of infrastructure. This step took the bulk of the time. Our particular process was:

1. Change code reviews to point to 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
2. Clone a couple of CI builds to run from the Git repository, side-by-side with their corresonding 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;
• Updating 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 enables roll back of any single change without affecting the entire migration. At the end of this phase, all of the infrastructure will be running off Git, while developers are 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 several issues. Once a team decides to cut over from SVN to Git, it must ensure that it is at a point where the cost of rolling forward through any issues is manageable.

4. Cut over

Once the infrastructure has moved over successfully, it's time for the final cut over, in which developers commit to Git not SVN.

Figure 4: The final operational cut over.

Some advice here:

• Broadcast the date of this change loudly, clearly, and widely across your organization;
• At the specified time, make the 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 the SVN repository is made read-only, run the 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 (such as a link to an SVN revision number in a code review) or a very old branch of code that builds from source.

At this point, we were now officially on 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?

The opinions of JIRA developers on the migration varied from, "Git is the most wonderful thing to ever happen to JIRA," to, "I know Git's better than SVN, but I need training," to, "Just show me how to do what I currently do in SVN in Git." It's critical to address the needs of developers across this spectrum.

I'm a developer. The VCS you use (along with some other things like programming language, IDE, frameworks, and libraries) is one of your core tools and one of the key areas where you develop skills. Your VCS is the vehicle for technical communication and collaboration. You need to ensure that all developers are fully on board to maximize their own potential. If a developer has any uncertainty or hang-ups about the tools they use, particularly their VCS, their work can be severely impeded. A culture of open communication really helps here. If you are going to change key tools in the development environment, it needs to be a change that the developers own and embrace.

1. Your team will need training

Assuming that everyone in your organization can learn Git on-the-fly after the migration is finished is a recipe for failure. Git is fundamentally different to SVN. Being aware of this, making your developers aware of this, and preparing them for Git is critical in making the migration a success.

The first thing we did to get our developers ready was to run a couple of Git training sessions. For example, we started out with, "How to do what you do in SVN, in Git." This included Git commands for things like committing and demonstrating what tools are available (developers at Atlassian use their IDE, SourceTree, gitg, and the command line to work with Git). More importantly, it focused on explaining the key differences between SVN and Git. What does it mean to have a local repository that's a clone of the remote repository? What is a working copy? What is the staging area? Finally, a step-by-step guide to cloning the Git repository and getting started fast was introduced and published on our extranet.

One of our tech leads also ran a deep dive seminar into how Git works internally — what data structures it uses and how actual operations like committing work are done. This was optional for all developers, but some people learn by deep investigation. Also, the more you delve, the more you discover that Git has a wonderfully elegant internal architecture, which is valuable for any computer scientist to learn.

We ran these training sessions internally, however there are a several external companies that run Git training, if that is your preference.

2. Your team wants to know how the migration is proceeding

While we were running the migration, we kept the team up-to-date on the status via email and HipChat, our real-time group chat product. Every time we reached a milestone, we let the team know. Every time we changed infrastructure, we let the team know. We did this partly as a warning in case things broke, but also to keep them updated on how the migration was progressing. It's a satisfying feeling when you say to a team member, "Hey, you know that code review you just created, you actually created it off the Git repository," especially if you can pull it off without anything failing during the change. This regular communication, from within the team, was essential in making each developer feel like they were up-to-date and owning the change. The worst outcome results if the team feels like this change is forced from outside, or if the tools they use every day are changing under them without their knowledge.