7 Things That Make a Great Open Source Contribution

I’ve been contributing to open source projects since the 1990s. In my years leading projects like WWW::Mechanize, ack, and Perl’s core testing functionality, I’ve made and seen many contributions. And I’ve learned a very important truth: While all contributions are valuable, even if they go unused, some contributions are better than others. I’ve also discovered that the best contributions, the ones that significantly improve the quality of the project and make life easier for the project leaders, share certain characteristics.

keyboard button reading open source

See also: The Beginner’s Guide to Contributing to Open Source Projects and The 8 Essential Traits of a Great Open Source Contributor.

The seven traits listed here should be a guide for anyone who wants to make their contributions to open source projects as valuable as possible. A good open source contribution should be:

1. A single, limited idea, clearly communicated

Your patch should be a single focus, limited in scope, and clearly described. (Note: I use the term “patch” to refer to a set of changes submitted to a project. Whether these changes are submitted as an actual patch or diff posted to a mailing list, or are a pull request on GitHub, the principles are the same.)

For example, a patch might include any one of these various types of changes:

* Fix ticket #741: Name validation should be case-insensitive.

* Add three entries to the FAQ covering internationalization.

* Change all occurrences of xopen() to yopen().

* Clarify wording of error messages in calls to logger.

* Replace about half of the uses of male pronouns in the docs to female.

* Update the packaging script to be more flexible in finding tools when running under Windows.

Note that a single idea doesn’t mean a patch is necessarily small in size. Changing all xopen() calls to yopen() might touch dozens of files, but the nature of the change is focused on one task, or one specific goal.

Your patch should change as little as possible in the surrounding code. Everything that you submit will have to be checked by someone else on the project, and adding unnecessary changes makes it harder for that person to understand the patch as a unit.

Here’s what you do not want to do:

* Fix ticket #741: Name validation should be case-insensitive. Also, clarify wording of error messages in calls to logger.

This change combines two unrelated tasks: Fixing name validation and changing error messages. It’s common to be working on part of the code and find other changes that also need to be made, and those changes should indeed be made. However, the two changes should be submitted separately. Create one patch to fix the bug, and another to improve the error messages. This makes it easier to understand each patch, and it helps the project manager address one while keeping the other on hold, if necessary.

2. Well-documented and summarized

Any patch you submit should be accompanied by a clear description, whether it’s on a mailing list or in a trouble ticket or a comment on a pull request. The description should explain what is being changed, why it is important to change it, and how the changes work.

For example:

This patch fixes ticket #741. User records were being rejected because name matching was case-sensitive. Four different regular expressions in three different files had the /i flag added.

Or another:

This patch changes all internal use of xopen() to yopen().

Using the yopen() API gives us more robust error-checking and allows for more flexible file handling on remote file systems. Besides a simple search-and-replace, files foo.c and bar.c had to be updated to handle new error cases.

Writing a summary like that helps both the contributor and the reader. For the reader, it gives an idea of what to expect, and makes it easier to understand the actual code being changed. For you, the contributor, it helps ensure that you are changing only the areas that should be changed.

3. Complete

Half-completed contributions have value, but require someone else on the project to make them ready for inclusion. It’s great to find a bug and create code that fixes it, but that probably isn’t everything the project needs. For example, in my ack project, a bug fix needs all these actions to take place:

a) A ticket in the bug tracker must be opened, with the problem described.

b) A patch or pull request must be submitted for review by others in the project.

c) A test case must be written in the test suite.

d) Documentation may need to be created or updated.

e) The Changes file must be updated to describe the fix, including the author’s name.

f) The contributor’s name must be added to the Acknowledgements section of the docs.

g) New files may need to be added to the manifest for inclusion in the package.

h) The bug must be closed in the bug tracker.

For most projects, there’s no such thing as a “simple two-line patch.”

Another area where contributions can fall short is in updates to the documentation. Maybe a sentence or two gets added to the docs or the wiki, but is that enough? Should the FAQ be updated as well? Are there other parts of the docs that could also use a relevant update? Nothing’s more frustrating than docs that say two different things in two different places.

4. Considerate of all users, not just the contributor

It’s easy to look at an improvement to a piece of code that fits your specific needs, but it may not be the best improvement for the majority of the users.

I often get patches and pull requests for ack where the patch makes sense for the author, but doesn’t for the community of users as a whole. While you don’t necessarily need to understand the project’s entire user base, sometimes your change might be too focused and specific for inclusion in the main project. In times like that, see if there’s an alternate way to get your change in the project. For example, maybe a behavior that doesn’t make sense to change for the entire project could be implemented with an alternate command line switch or configuration parameter.

5. Written to match the rest of the project

Most projects have a coding style, even if it’s not written. Your contribution should match the coding style of the rest of the project, even if it’s not how you prefer to do things.

If the project’s code looks like this, indented with spaces:

while ( my $user = next_user( FOO, BAR ) ) {

    process( $user );

}

then follow that style and don’t contribute patches that look like this, indented with tabs:

my $user;

while ($user=next_user(FOO,BAR))

    {

    process( $user );

    }

Not every project has a codified set of coding style standards, but that doesn’t mean you can’t observe and figure them out for yourself. The project’s style may not match your personal coding preference, but a patch is not the place to make a statement of what your preferences are.

6. Designed to minimize the amount of new code or writing

Every line of code in the codebase has a cost in terms of future costs on the project. It adds to the weight of the project and the number of things that can go wrong, or become outdated.

After you’ve made your fixes or improvements, take a look at a diff and see if there’s anything you can do to reduce the footprint. Maybe there’s a helper function elsewhere in the project that can let you remove a few lines of code, for example.

The best code is code that doesn’t have to be written or maintained. Your patch should make as little new code as possible.

7. Reviewed by someone else

Before you submit your patch to the project for review, which may include dozens of people who will read it, have someone else proofread it. This person doesn’t even have to be familiar with the project, but should be able to get a general idea of what you’re doing. Maybe you haven’t explained the patch clearly, or maybe your test cases don’t look extensive enough. A third party may well catch these things before you ship if off to be reviewed.

Contributing to open source projects is important work. Projects rely on new contributors coming in as others lose interest or switch to other projects. The list of attributes in this post should help your contributions have a big impact on the projects you use.

Open source and keyboard image courtesy Shutterstock.com

Andy Lester has been involved with open source for two decades, contributing many modules to Perl's CPAN as well as speaking at open source conferences and user groups around the country. He's the author of the search tool ack and his book Land The Tech Job You Love is published by Pragmatic Bookshelf. View posts by .

Interested in writing for New Relic Blog? Send us a pitch!