Cyberborean Chronicles

Open Source Best Practices: Part II (Technology)

How to get a succesful open source project:
The beginners guide.

II. Technology

Version Control

Open source development without networked version control system is like a running on crutches. It is not enough to publish your sources on FTP or web-server for free download. Very soon you’ll start to receive the patches and bugfixes and will face with lack of resources to manage them and maintain the product. So, an idea to have a shared sourcecode repository and to allow active contributors to apply their changes themselves is obvious.

Using the Concurrent Versions System (CVS) or Subversion is a common practice for collaborative opensource development. There is no matter how large or small is your community or a code base. Learn it. Use it. It is a necessary condition of successfull teamwork.

A knowledge and a lot of helpful tips on using CVS for opensource projects can be obtained from Bar&Fogel book [2].

Project workplace

There are free internet services which provide hosting of opensource projects and an infrastructure for collaborative development. As user of that service, you are supplied with a solid workplace for your team and got rid of many infrastructural aspects of project maintaining. If you’re in doubt where to go, register the project on the SourceForge.net — a popular and mature workplace for opensource development which provides almost everything you need for your project, including:

  • CVS repository
  • Hosting of the public web-site
  • Mailing lists and web forums
  • Public bugs, patches and feature requests tracking system
  • Time-tracking and task scheduling tools for development planning
  • File releasing system with a number of mirrors around the world
  • Tools for advertising your project and recruiting new members

The only problem with SourceForge (although, it is common for today’s internet) is a namespace issue. It is rather hard to register new project with a sensible word as its name there…

Web-site

Web-site is a public facade of the project and a powerful tool for supporting the users, recruiting new members and project advertising. Run and support it from a very initial stage of your project. The web-site of the open-source project typically contains the following information:

  • Project news, including the announcements of new releases.
  • Project overview — a brief introduction into the software, project and its mission.
  • Documentation: User’s Guide, HOWTO and FAQ, articles, developers documentation etc.
  • Download page, including a guide on how to download, build and install the software
  • Development overview (or “Get Involved” page) — describes the development process, including information on how to join the project for new contributors, as well as how to report bugs, submit patches etc.
  • Contributors list
  • “Contact us” page, including email adresses of project coordinators, mailing lists subscription etc.

Keep the web-site content in an actual state. It is a good idea to put content in CVS for collaborative updating.

Mailing lists

The mailing lists are conventional tools for communication among the project’s community and users. Typically, an opensource project runs the following types of lists:

  • Developers mailing list — a main discussion forum of the community.
  • Users mailing list is for discussions among end-users and developers. It is where users can get help either from developers or from other users.
  • Announce mailing list is a sort of newsletter for the people who want to be notified on new software releases.
  • CVS automated mailing list is helpful for CVS users who want to be notified about every change in the code repository.

Public bug trackers

Encourage users to report the bugs using a special bug-tracking service on the project’s web-site. It allows your team to keep a consistent bugs database and fix them faster.

Read more on bug tracking at Joel On Software: Painless Bug Tracking.

It is also a good idea to use the tracking tools for new feature requests and software patches submissions.

Downloadable file releases

Make new release every time when a noticeable bunch of new features or bugfixes is done (an opensource everyday wisdom is “Release early, release often”). It may seems unnecessary if the project provides an anonymous CVS read access, but the most of end-users don’t use CVS and prefer to download the file releases. It is also a reason for good practice of making the “nightly CVS tarballs” — the downloadable archived copies of the whole repository built automatically at every night.

Besides the sourcecode release, provide a prebuilt binary version— for those users, who cannot or don’t want to compile it on their own side.

Automated building

Don’t make other developers and users to install your favourite development tools to build the sourcecode. Use conventional automated build systems — such as Ant for Java projects or make for C/C++. Building the sources should be simple as possible. In an ideal case, an user should only run the build script to get the software compiled and ready to start.

It is a good practice to use a build script as a central point for complete code management — not only for compilation, but also for product installation, building a documentation, tests running, making the releases, launching CVS functions etc.

Automated testing

A practice of the “test-driven development” with automated testing frameworks such as JUnit, saves a lot of time for debugging and provides more reliable and bugs-free code in comparison with manual testing. Write test cases for everything and run them so often as possible to be sure that the code is workable. Encourage other developers to write test cases for their new features.

This is especially important for teamwork, because the situations when someone accidentally breaks other’s code are not unusual. Providing the “quality requirements” in a form of test cases and suites smoothes the problem. When developers are used to run the test suite before each CVS commit, the code in the repository will never be broken and be always kept in a workable state.

Good software design and usable code

Good software design increases the developers productivity. If you think these are buzzwords of commercial software industry, you’re wrong. As it was said above, the time of developers work is a most valuable capital of an opensource project and don’t let it be spent for long investigating and learning an existing code. Every programmer knows how difficult the exploring of another’s code might be, so produce an evident design and usable code from very initial stage of the product. Your initial code is a foundation for all subsequent add-ons and if it is well-designed, it will encourage other developers to keep and follow that design as well. The developers are enjoyed by a well-designed code and it motivates them to work with it, while the intricate, hard, obfuscating code makes them tired and they leave the project.

Use conventional object-oriented design techniques with thought-out classes hierarchy, concern separation and effective modularization. Provide a consistent and documented software API as a basis of the whole application. Think over the consistent and understandable identifiers scheme and comment the code where possible. It will save a lot of developers (and yours) work hours in future.

Design patterns

Design patterns are succesfull solutions which can be repeatedly used in various applications. In object-oriented design they are predefined organizations of classes and relations among them, such as well-known Factories, Iterators etc. The comprehensive guide on using the patterns in OO design, including their taxonomy and classification is given in the “ Design Patterns: Elements of Reusable Object-Oriented Software” classical book by Erich Gamma et al.[3]

Usage of patterns improves a software design and understandability of the source code. It also provides a common vocabulary for developers discussions, so you always can say: “I gonna implement a Facade pattern there”, instead of long explanations of what do you want to do.

A component technology

Think about your program as it is a framework for random features of specific problem domain, rather than a specific fixed set of features. The component-oriented programming techniques benefit not only for good software design and product flexibility, but also for community. When specific pieces of functionality are designed as the separate modules (or, “plug-ins”), the development process can be splitted into few independent lines with their own developers and maintainers. So, new developer who interested in specific feature can quickly start to work around it without diving into the whole code base. It makes adding new features simple and your community will not spend a time for flaming about where to go and what set of features a software should contain. When someone falls in opposition with her idea of a new feature, she can develop it as a plug-in and let users decide themselves on using it.

Avoid to reinvent the wheels

Learn about common standards, practicalities and third-party solutions which can be used in your software. They will save a lot of time for you and your community. For instance, if your program needs for a structured data format, use XML instead of your newly invented one. Before going to implement some feature which doesn’t seem unique for your area, try to look for appropriate third-party solution. The development process will go faster and new developers probably will be already experienced in that technology, so they will be able to start a “real work” immediately.

Using well-known and conventional technologies increases the speed of development, because it increases an amount of the “shared knowledge” in community.

Documentation

An another way to improve the “community knowledge” is to document everything whenever possible. I mean not only the user manuals and help, but also technical documentation written by developers for developers.

The tools like wiki make a great help for this.

Internationalization

Your software will be used around the planet by people speaking various languages. Although the English is a conventional language of opensource culture, the people prefer to use localized software in their countries. Don’t use hardcoded labels, messages and other locale-sensitive data in the program, but provide flexible localization framework enabling easy replacing default values with their local equivalents.

National localization is also a good way to attract new project members (see the “Motivate users to contribute” section). By my own experience, many of active developers started from contributing the localization packages for their native languages.

Accept donations

Some people or organizations would like to support your project with money or other resources. This is good and you should not reject such kind of contribution — after all, this is equivalent of that other people contribute their labour. Leaving aside the time and efforts you invest into the project (assuming you compensate it with fun and satisfaction of your own technology needs), you usually bear direct costs on hardware equipment, internet connection, domain name support and so on. So, money donations are undoubtlessly helpful for the project.

… and have fun

This is a final recommendation, that I’d like to tell. Be enjoyed of your project and let the people be enjoyed of it. Don’t let it become a boring thing. Boredom is the main enemy of an opensource.

Happy coding!

Bibliography

1. Raymond, Eric Steven. “The Cathedral and the Bazaar”. 1999, O’Reilly, Sebastopol, CA.
2. Bar, Moshe and Karl Fogel. “Open Source Development with CVS”, 3rd Edition. 2003, Paraglyph Press, ScottsDale, AZ.
3. Gamma, Erich, Richard Helm, Ralph Johnson, John Vlissides. “Design Patterns: Elements of Reusable Object-Oriented Software”. 1995, Addison-Wesley Longman, Reading, MA.

Leave a Reply