By Mike Jackson.

Sometimes it is necessary to move your project resources. This might mean moving your website, code repository, email lists, issue trackers and other resources. Sometimes you choose to move, because it will make life easier. Your resources might be spread over a number of servers, so you're choosing to move them so that you can unify your resources. Sometimes a move is thrust upon you by circumstances, such as your current servers or repository coming to the end of their lifetime. In this guide, we will list the steps you should consider before a project migration.

We've kept this guide technology-agnostic, so it should be relevant to any migration. Technical details about exporting from and importing into specific repositories are dealt with in other guides.

Why write this guide?

Various projects asked us about migrating between repositories when the NeSCForge site shut down. We wrote a few guides to cover different aspects of the process. In this guide, we focus on the migration process.

Remember to communicate

The most important thing is to communicate. You need ensure that those affected - users, developers and other interested parties - are aware of your plans. These people will want to know the answers to a number of questions, mainly:

• When are you migrating?
• Why are you migrating?
• What has been migrated?
• Where are you migrating to?
• What other changes have been made? (changes to the way in which resources will be accessed and managed, changes to how users communicate with your project)

Some of these questions are needed simply for information, such as the date of migration. However, other questions are more far reaching. When you migrate your code, your users and developers will most probably need to make changes to the way they work. It's worth investing some time to properly explain why you are moving. This keeps your user base on your side, especially if they will receive a better service after the move (or you simply had no choice but to move). You can also keep your userbase happy by including them in important decisions.

Decide on, then publish your migration date

The migration date is the point at which you agree that the current resources will no longer be used and interested parties must switch to using the new repository. You may be lucky and be able to select a migration date at your leisure. On the other hand, you might find that your current repository provider has just received a hard deadline after which time they will shut down. In this case, the migration date would ideally be some time before the shut down date, to provide for breathing space in case of problems.

Ideally, the migration date should be chosen after discussion with key stakeholders. This is especially important for open-source projects with distributed teams. Once you've decided on a date, it is very important that you make your entire community aware of it. The migration date should be publicised on all your current communication channels: email lists, forums, website and blog.

Find out what you can migrate

Discuss with your current repository administrator, or server providers, which resources you'll be able to keep and which you won't. For example, some repositories might allow you to retrieve your source-code repository and uploaded documents, but not wiki text or forum posts. Some may allow these to be accessed easily through, say, a secure file transfer, whereas others may require you to manually download files.

Decide what you want to migrate

It's one thing to be able to migrate a project, it's another to actually want to. You may just want to export certain resources and archive them locally, for historical value, but not migrate them to your new repository.

A good rule-of-thumb is will a user, developer or project member find this useful in future? For example, source code may be essential, a document about the pros and cons of design options may be useful for developers, but a list of meeting agendas from years ago will have less value.

A hidden benefit of migrating your project is that you get the opportunity - or excuse - to spring clean your project's resources.

Decide on where you want to host your resources

If you haven't already done so, you'll need to decide on a new repository. We've written a guide on Choosing a repository for your software project that discusses the issues to consider.

What you can keep from your current repository, what you want to keep and your plans for the future may all contribute to your decision. For example, would you be able to migrate your complete source code repository or the contents of your ticketing system into a new repository?

Set up your new repository

It's advisable to set up your new repository in advance of the migration. This allows you to familiarise yourself with how to configure and administer the new repository, which allows for smoother running during the migration. You can also ensure that users and developers have logins (if required) well in advance of the chosen migration date.

It's a good idea to prepare a short guide that describes how the new repository works. How do you access the source code repository, how do you ask for help, where to find what information, etc.

You may want to add some simple content to the repository so that users and developers can familiarise themselves with the repository and get back you to point out bugs or suggest changes.

Migrate!

When the migration date comes, migrate! Export all your resources from their current homes and import the chosen ones to the new repository. Make sure you test everything, such as the source code repository check-outs and check-ins and emailing lists.

Let the community know you've moved

Once you've migrated, publicise this fact on all your current communication channels. This is very important, because you could drastically reduce your community if you move and don't tell everyone.

You should mark your existing (now former) resources as deprecated and have links redirecting users to the corresponding resources in your new repository. If time allows, it's worth tracking down links to your resources from other project's sites and updating these links to point to the new repository (or asking their webmasters to update them).

It's also be worth checking if the administrator of your former resources can provide automatic redirection of links from your old to new resources.

Mop up the waifs and strays

It's inevitable that you will get stragglers, especially on email lists or forums, so it's useful to bounce them across to your new resources. For example, if a user asks for help in a deprecated forum, you can nudge them in the right direction by replying: "please resubmit your request to ..." This may seem harsh, but it discourages people from continuing to use deprecated resources (and if they really need help, they won't mind).