Top tips for migrating to an open source repository

Posted by m.jackson on 20 April 2012 - 2:50pm

CliffJump.jpgYou've decided to make the leap and move your software to an open-source repository. You may be doing this for reasons of openness - to encourage a community of developers to evolve around your software - or economics - to outsource the maintenance of your source code repository, email lists, wiki, blog and other services to a third-party who offers these for free.

Before you plunge into this brave new world, we invite you to consider our five top tips for moving your software to an open-source repository, to ensure that your migration is a pleasurable one.

1. Get buy-in from your developers

As your developers will be using the repository day-to-day, they need to be on-board from the outset. You do not want to take the time to create a project in a repository only to have it sit there unused, because your developers don't like its revision control system (or can't see the point of it).

Talk to your developers and let them know why you're moving to a repository and explain the implications and benefits for them. If you can convince your developers that the move is necessary, your migration to a repository is far more likely to be successful.

2. Keep everyone informed

If you have an existing community of users or developers, you must keep them informed of your plans and progress. Specifically, you should tell them what you are migrating, when the migration takes place and the implications for the users and developers. The latter is particularly important, because the move to an open-source repository will almost certainly have implications on how and where users can download your software or source code, or how developers access the repository.

It's a good idea to provide a short, before-and-after guide noting how things are done now (e.g. checking out code) and how they will be done in the new repository. For more on planning a migration, see our guide on migrating project resources: what to remember.

3. Choose a repository based on both your current and future needs.

There are many repositories out there (e.g. SourceForge, GitHub, and LaunchPad) so don't just choose the first one you come across. Assess your options as you would when choosing any tool.

  • Does it offer the functionality you need?
  • Does it support your (and your developers') favoured revision control tool?
  • How established is the repository?
  • Does it have evidence of a future?
  • Do you have colleagues in your field who already use it?
  • What are their experiences of it?
  • Does it offer the quality of service you need (e.g. do they back up their servers, do they bring new servers on line regularly, are the services responsive?)
  • How easy is it to administer and use?
  • How easy is it to get your existing content (your source code repository, including any history, documentation and other data) into the repository?
  • How easy is it to get your content out again to back it up?

Remember not just to consider what you need right now, but also what you may want in future. For more information, see our guide on choosing a repository for your software project.

4. Choose your project name carefully

It is easy to quickly decide upon a project name then create a project in your repository, set up email lists and upload your code. However, you may soon decide that your choice of name was not the best (for example, someone else has a project with a very similar name) and wish to change it. Once it's established in your repository, changing your project name might require a lot of work. It might even require contact with the repository provider.

Thinking carefully when setting up the repository could save a lot of pain later. For more information, see our guide on choosing project and product names.

5. Identify an administrator

Someone has to take responsibility for creating your project in the repository, understanding and managing its configuration, creating accounts for developers and keeping things ticking over. Furthermore, this someone has to have the time and inclination to do the work! Identify an administrator early on - better yet, identify two administrators, so the knowledge is shared!

6. Write a "quick start" guide for your repository.

The amount of documentation provided by open-source repositories can be rather overwhelming, especially for people who use only a subset of the services.

It's worth writing a quick start guide that summarises how your project is organised, the features that you use, what you use them for, and how to configure and use them. The guide doesn't have to be comprehensive, it need just cover the things you, your users and developers will use day-to-day. You'll often find that writing this guide, and getting others to use it, helps both improve your understanding of the repository and the guide itself.

There you have it, our top tips on migrating to a repository... let us know what you think!