June 19, 2006

Contributing to FLOSS projects

Author: Leslie P. Polzer

As a free software maintainer, I get to read lots of email messages by people who want to contribute to the projects I am responsible for. Most of them know little about the Free/Libre/Open Source Software culture. Here are some tips that every aspiring developer should know about the customs and techniques prevalent in FLOSS culture and about contributing to FLOSS projects.

An ability and readiness to read and gather information is a prerequisite for anyone wanting to participate in the FLOSS community, be it with bug reports, code, or advice. Often a document will convey information more effectively than an email exchange or IRC conversation. This is especially the case for general topics.

Before sending questions to a project, be sure to have exhausted other resources. The document "Asking smart questions" by Eric S. Raymond will help you find these resources and tell you more about the art of smart questions. Use your favourite search engine, the archives of the project's mailing lists, related wikis, and so on.

If you are looking for specialized information, or information you could not find on your own, do not be afraid to ask for pointers. Most FLOSS people are happy to send you links to the documents you need. Honour this service by actually reading them; they are usually hand-picked resources that will help you.

Another important practice is to use a project before contributing to it. This will help you get an idea about its structure, its needs, and maybe some hints for contributing. Read the relevant top-level files in the source tree. They are often called README, CONTRIBUTING, HACKING, or TODO. It is best to use the latest sources from the project's code repository, but the latest source archive will also do in most cases.

Contacting the maintainer

After you have gathered enough information, find out who is responsible for introducing new developers to the project. The preferred way for doing this differs between projects. Some prefer IRC, while others like mailing lists better. Small projects often have only a single person to contact. The Web site of the project and the files mentioned in the last section will give you an idea of how to proceed. It is often a good idea to ask whether other people are already working on a task or have done so in the past, even if you feel that you could start working right away.

When you have found the suitable way and direction of contact, write a message. Be specific about what your aims and abilities are. Do not be overly polite -- business-speak is not usual. Write as if you are addressing a peer: be respectful, but do not overdo it.

An example:

Hello Leslie,

In your job advertisement for GNU fdisk on Savannah you are asking for new developers. While I have not contributed to a free software project before, I have qualifications in C and believe that I can do something useful.

I'm interested in helping with the user interface parts. Perhaps a completion framework would be useful? A similar thing already exists in many other software packages.

Can you give me a few hints on tasks that would fit my interests?

Happy hacking,


Your English need not be perfect; I have yet to meet a FLOSS person who got angry at someone whose English contained mistakes.

Selecting a task

Once you have gathered a list of tasks that need attention, choose the one among them that suits you best. After that, download the latest developer source (often available with the help of a revision control system such as CVS, Subversion, or GNU Arch)and modify it. Be sure to follow the project's policies on coding style and any other conventions.

When you feel that your contribution is ready for inclusion, you must create a patch, which is a file that records changes between files. If you are working with distribution archives or snapshots of a project, you need a pristine version of the code to compare to your modified version. Give the two versions distinct names and compare them with the "diff" command:

diff -Napur project-3.2.pristine project-3.2.modified > my.patch

If you are working with revision control systems, there are special commands that show your changes:

CVS: cvs diff > my.patch
Subversion: svn diff > my.patch
GNU Arch: tla changes > my.patch

The resulting patch file should be submitted to the project's mailing list or personally to a developer responsible for incorporating patches; again, see the project's guidelines on this. Usually your patch will be reviewed and you will be asked to modify problematic spots, if any are found. In that case, just correct them as directed and create a new patch. After your proposed changes pass a peer review they will be applied to the project's sources.


Working with the FLOSS community is easy. Being respectful, polite, and professional in your actions is very important -- much more than being so in words. Besides that, not many additional skills are required, apart from the project-specific abilities to do the job. People are glad to help you get started when you show them that you are serious about it and willing to put work into it.

Click Here!