By Mike Jackson.
You've taken the big step: your software is now hosted in an open-source repository. You can rest easy, right? Well... no. A repository is like a well-engineered machine, it requires care, attention and nurturing so it can continue to deliver the best performance. Treat it well and it will treat you well!
Here, we present our five top tips for using an open-source repository.
1. Use it!
"Of course I'll use it. After all, I did all that work setting up the repository..."
Typically there will be a transitionary phase after you've set up your new project, where you iron out any wrinkles and continue to use your existing resources as a back up. Once all of the issues with the new repository have been resolved, it is vital that everyone on your project switches to the repository. This may be easy if, for example, a local server hosting your source-code repository is to be decommisioned. But sometimes it will be more difficult, esepcially if your developers host source code on their desktop machines.
This is problem of ensuring buy-in from your developers (and for more on this problem, see our top tips for migrating to an open source repository). You need to encourage your developers to change to repository-based practices: raise tickets for bugs rather than just fixing them silently, and discuss aspects of the software via the project's email lists rather than in one-to-one emails.
2. Monitor your use of the repository's services
Repositories provide myriad services for communicating with users and developers: blogs, forums, email lists, and wikis. These can prove a navigational nightmare to new users.
People may click on links only to find a blog with no posts, forums with no entries and empty wiki pages. Empty service pages like these can lead people to conclude that your project is dead. After all, clear evidence of ongoing effort is a popular metric for ensuring that you choose live open-source software (see the OSS Watch's top tips when selecting open-source software).
Make your project easier to navigate - and less likely to look dead - by disabling services that you are not using. Reponsitories usually provide administrator interfaces for this purpose. You can always re-enable the services later.
3. Watch third-party licences
It's one thing to dump commonly-used third-party binaries, JAR files or code in your own in-house private repository for easy access, but it's quite another to dump it into an open-source repository because this counts as redistribution. Certain licences (especially proprietary licences) preclude redistribution, so make sure you understand the restrictions in the licences before you commit third-party files to your repository.
For more on software licences, especially open-source licences, check out OSS Watch.
4. Keep it clean!
Both wikis and source-code repositories can easily evolve into an unstructured and confusing mess, and this will make liife difficult for your users and developers. Ticketing systems can give rise to ever increasing numbers of new, unassigned tickets, which gives the impression that there is little activity on your project and can deter potential users.
You should regularly review the structure of your source-code repository and refactor your code to keep it understandable. Wikis should be restructured to make them more easily navigable. Tickets should be regularly reviewed, and those that are not important should be closed (remember to make sure that you state the reasons why they're being closed).
5. Back up regularly
It is highly recommended that you regularly back up your repository content. Yes, the repository providers should be doing back-ups themselves (and if they don't, you probably shouldn't be using their services!) but it is better to be safe than sorry. You can never have too many backups!
Many repositories provide support for backing up your content. For example, SourceForge allows you to back up your project configuration, blog, wiki, tickets, email lists and source-code repository, and it is possible to write a Perl script to do this automatically from your local machines.
There you have it, our top tips on using repositories. Why don't you tell us what you think!