Contributing to Open Source Projects HOWTO

This page is aimed at programmers new to the Open Source / Free Software world, who want to make a contribution, but aren't sure where to start.

The latest version of this document is at www.kegel.com/academy/opensource.html.

Contents

Triage

Triage is the fine art of looking at bug reports from users, deciding if they're repeatable, and if so, passing the proper information on to the developers. This is a great way to get familiar with a project, and to earn karma points. A guide to triage of OpenOffice bugs is online at kegel.com/openoffice Other projects with bug report backlogs that could use triage include

Patches

Most open source projects work like this: all the developers have their own (not quite identical) copies of the source code. When one developer has a change he wants to share with the others, he emails them a patch.

Making Patches

To create a patch, you run a program called diff, and save its output to a file. For instance, if the original source tree is in directory "foobar.old", and your new sources are in directory "foobar.new", the command That would merge the changes from blarg.patch into your source tree. (The -p1 tells patch to ignore the first directory in filenames in the patch; that way a patch generated against the directory foobar-0.11 will still apply properly.)

patch is part of the Gnu Project; to learn more, read "Merging with Patch" in the GNU project's manual for diff.

Licensing

Before you submit a patch, be sure you understand the basics of software licensing, otherwise your patch might be rejected for legal reasons.

Here are some rules of thumb:

See www.denniskennedy.com/opensourcelaw.htm for more info on licenses.

Culture

The culture of successful open source projects, e.g. the Linux kernel, is described in the following pages:

Gnu Autotools

Many open source projects make use of the Gnu Autotools to generate their Makefiles. The learning curve for the Autotools is steep, but a few tutorials are available. Here are some places to start:

CVS

CVS is a source code control system that automates and hides the work of using diff and patch. You'll get to know cvs later; when starting out, it's best to learn how to use diff and patch. (But if you're curious, you can learn about cvs at cvshome.org.)

Example: Fixing a #include problem

Here's how one newcomer jumped in and started contributing.
  1. Since he didn't have Linux, he downloaded and installed Cygwin to give his Windows system the tools needed to build Linux programs to run on Windows. (Note: you have to pick the "Development" package in the installer to get the C compiler! Cygwin's installer's user interface takes some learning.)
  2. He went to freshmeat.net and browsed around until he found a project that looked interesting. His choice was Clex, a curses-based file manager (see http:/www.clex.sk).
  3. He downloaded the clex source code from its home page's download page (in particular, he downloaded the file www.clex.sk/download/clex-3.1.7.src.tar.gz), and unpacked it with the command This failed with the compiler error
  4. To make sure his patch really worked, he read a tutorial on how to use 'patch', then unpacked the clex source code again into a new directory, applied the patch with the command Here's the patch he attached: (See the GNU diff manual's description of unified diff format for an explanation of what those +'s and -'s mean.) And here's the shell script he attached: Try installing Cygwin on a Windows system, and see if his shell script correctly downloads, patches, and builds Clex! (You may need to apply the patch by hand, since it's hard to copy and paste patches from web pages.)

    Suggestions

    Now that you've seen examples of how to contribute to an existing project, here are some suggestions for picking projects to contribute to.

    The best way to find projects to contribute to is to simply use open source software for all your day to day computing needs. As time goes on, you will find rough edges here and there. Pick one of the smallest rough edges you can find, and post a patch that makes things work better.

    Some projects maintain "to-do" lists for people who want to fix problems others have already identified. Here are a few:

    Also, here are a few small project ideas:

    Testing

    Several of the following project ideas have to do with testing. Here are a couple web pages on the subject that are worth reading:

    Invalid Input Testing

    All programs that process responses from remote servers should be able to withstand invalid and possibly malicious responses without crashing. Yet few programs are tested to make sure they can, let alone designed with this in mind. See for instance: Your assignment, should you choose to accept it, is to write a tool to do similar testing on some other program that accepts data from strangers (e.g. OpenOffice, xpdf, Macromedia Flash plugin, Sun JVM) and see if you can get it to crash in a nasty way. If you can, submit your test program to the maintainers of the application, and file a bug report in the application's bug tracking system.

    Unit Test Coverage Improvement

    1. Find some project that has a test suite (e.g. Wine, ACE/TAO, OpenOffice.org).
    2. Figure out how to build the project with the compiler options needed for gcov.
    3. If the project is autoconf-based, submit a patch to the project to add a --enable-gcov configure option. (See e.g. Aaron Arvey's patch for Wine.)
    4. Measure the coverage of the test suite for one of the project's source files or modules. e.g. for Wine, measure the coverage for the source code of one DLL. (lcov may come in handy if you want an overview of a large project's test suite coverage, but you'll probably want plain old gcov once you've picked what part of the project to focus on.)
    5. Add cases to the test suite to increase the coverage.
    6. Submit these test cases to the project.

    Wine Header Cleanup

    Wine comes with its own copy of <windows.h>, to allow compiling Windows programs for Linux. However, Wine's version of windows.h isn't quite complete. As Dimitrie Paun pointed out, it uses macros when it should be using inline functions; that would let it compile more programs. Try converting one of the macros into an inline function, verify that wine still builds, send your one-line patch to wine-devel@winehq.com and ask for feedback, and if they like it, submit it to wine-patches@winehq.com.

    Wine Command Shell Help Text

    Wine comes with wcmd.exe, a clone of the Windows Command Shell, cmd.exe. wcmd.exe doesn't have help text for some of its commands. It's fairly easy to add the missing text, once you know what the command does. Here's an example patch that adds the missing help text for one command.

    Continuous Integration Autobuilders

    There are several continuous build systems that watch over a source code repository, continuously building the project. This catches new errors much sooner than if some developer had to run into them, and increases the chances that bugs will be fixed before they get in the way. Here are links to a few: Read up on a couple of them, pick one, and try to set it up to watch a popular open source project (e.g. wine) and send you email whenever it finds problems. Once that's working, document how you set it up, and post the description to the mailing list for the project you set up the autobuilder for.

    See Also

    Last Change 22 Nov 2004
    (C) Dan Kegel 2003-2004
    [Return to www.kegel.com]