Encouraging Open Source Contribution

Leaders of the open source community are always trying to encourage others to contribute. Volunteer contributors are always in short supply, and most open source projects are driven by volunteers, so recruitment is a big component of any open source project lead. Elizabeth Naramore put together a great list of reasons why people tend to shy away from contributing and did a great job highlighting some solutions. I want to add my own voice and experience about one of the truisms of open source development:

When it comes to making open source easier, architecture matters.

Recently, I started contributing to Phergie, which is an open source bot for IRC written and maintained by Matthew Turland. The bot is by no means a simple application: it employs concepts like streams, sockets, the command line, web scraping and other concepts that are beyond introductory. Yet, as I write this, I’ve already contributed two plugins to Phergie with less than four hours worth of work, and not simple plugins either: one of them scrapes Google for conversions, and the other is a caching plugin to cache requests so that they need not be repeated.

How is it possible that I, a programmer with lots of experience but almost zero experience writing plugins for Phergie, was able to contribute so quickly? Is it because I’m a super programmer with above-average skills? No. It’s because Matthew Turland took the time to architect Phergie in such a way that adding a plugin is a cinch.

Marco Tabini pointed out that architecture doesn’t matter as much as having code that works. This is a fine point, and often times is true. But if you ask the average PHP developer if they want to write a plugin for WordPress, their answer would be no – the documentation isn’t great, the API is inconsistent, and the code base requires a bit of study before one can even begin making changes. Lots and lots of developers do develop plugins and contribute to WordPress’ core, but I doubt any of them would say it’s got a limited learning curve.

This isn’t meant to attack WordPress, or any other open source project for that matter. My point here is this: with one fell swoop, a well-architected project like Phergie can eliminate most of the barriers to entry that Elizabeth experienced. With Phergie, if you have a basic understanding of object-oriented programming, can write functions, use regular expressions and understand the PHP manual, you can contribute! Matthew has done the hard work for you, so that you can do the fun stuff you enjoy.

There are five keys to improving open source projects in such a way that they entice new developers to get involved:

• Use your core team to make the difficult and time-consuming choices. Make sure that when newcomers enter the project, they’re not confronted with architecture choices that have to be made.
• Make adding components “wiki” simple. Phergie’s strength lies in her plugin architecture, which allows functionality to be added with ease. A plugin needs nothing more than to extend the Phergie_Plugin_Abstract class and be added to the configuration. When you’re ready for advanced functionality, the project is docblocked and the documentation is there. Speaking of documentation…
• There should be good, solid, easy to use documentation. Not documentation generated automatically, but documentation written for beginners and edited by the beginners as they learn. It’s hard to explain advanced concepts to beginners when you invented those concepts, which is one of the things that makes Zend Framework so damn hard to learn; solicit your beginners to help you understand what they don’t understand. Matthew asked me to help him make the documentation easier to understand.
• Be actively involved in the project, answering questions and handling commits/pull requests. I have Matthew’s IM on my list; that doesn’t mean that you should talk to every contributor personally but do be active in answering questions, commenting on tickets, pulling code into the repository, and other aspects of the project. If the project’s leaders are hard to reach, people will be unwilling to contribute. By the way, Zend Framework gets props here: Matthew Weier O’Phinney has been exceptionally easy to ask for help, for which I am eternally grateful.
• Mentor newcomers from beginners into advanced developers. After contributing my first plugin, Matthew asked me if I had suggestions on an encoding bug he was experiencing. While the problem is still unsolved, it meant I dug into the internals, asked lots of questions, and learned a lot about how Phergie works. Matthew has worked hard to mentor me, and it will benefit his project.

Recruiting volunteers will always be a challenge in open source projects. But it can be made easier. The more volunteers get involved, the more improved and rich the projects will ultimately become.

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP

James Baugh (@jabbaugh) wrote at 4/7/2010 4:29 pm:

Thanks for writing this. I have been wanting to contribute to an OpenSource project for a while now, but I really don’t know where to begin. I have a good skill set (using PHP 4+ years and ZCE certified) but don’t know where to take my first bite.

Any suggestions?

Thanks

Wil Moore III (@wilmoore) wrote at 4/18/2010 9:15 pm:

James,

If you want to contribute to an open-source project, my suggestion would be to start with software you are using heavily. This is built-in incentive for you as a developer and makes it so much easier to dive into the internals since you most likely already know how the thing works.

Prior to being a heavy Zend Framework user, I wanted to contribute to the project. I found myself with lots of grand ideas but I was just spinning my wheels. After using the framework daily for a while, contributing became simple. I say this with the understanding that I still haven’t found the time to implement any of those “grand” ideas; however, just helping chip away at the small stuff has been fun and gratifying enough.

Here is my break-down of how to start (works for me but YMMV):

1 – Use the project in one of your own projects or find a way to use it at work.

2 – Start helping others by answering questions on IRC, the issue tracker, or comment the documentation/wiki.

3 – Periodically run the unit test suite. You may catch something that the original developer didn’t based on your platform and configuration.

4 – Fix the documentation…even if it is just to correct a typo. What you will find is that even if you are submitting a super-trivial patch (typo, correcting a coding standard violation, etc.) you are learning the process and getting familiar with the internals.

Besides, any end-user would agree that no project can have too many people contributing to the documentation.

Copyright © 2023 by Brandon Savage. All rights reserved.