5 Tips for Contributing to Open Source Software like Event Espresso

Many good software developers struggle and become frustrated when contributing to open source software. That’s because the skill set required for contributing to open source software is different from that required for writing closed source software.

About three years ago we decided to put our flagship WordPress plugin, Event Espresso, on Github in order to facilitate community contributions. It has always been open source (meaning the code that runs it is viewable by anyone who downloads it), but that made it much more accessible for contributions. Since then we have received numerous pull requests (requests to have code added to it), but not all contributions were ready. The purpose of this post is to help software developers better understand how to contribute to Event Espresso, WordPress, or any open source software.

Open Source Software Is Harder than Closed Source

In my experience, it’s much easier to work on closed source software by yourself than it is to contribute to an open source project. Although it may frustrate you at first, you should be grateful open source software maintainers don’t accept every pull request that comes their way. If you just consider security, closed source software can benefit from “security through obscurity“, meaning that even if the software has major security problems, they might never be exploited because the software may only run on a single site (and hackers won’t waste their time on it), and the problems might be very hard to guess because hackers don’t know exactly how the software works. In open source, such as WordPress or Event Espresso, it’s often running on tons of sites (so big target for hackers), its code is equally viewable by hackers and honest contributors alike (so hackers can spot exactly where the vulnerabilities are), and the icing on the cake: hackers themselves can submit a pull request with a known security hole in it! Yep, accepting pull requests is actually a big deal.

Some don’t grasp any of that complexity at first, or at least I didn’t. I’ve gone from closed source software developer (who thought knew what I was doing) to disgruntled open source contributor (who got upset with maintainers because they’d reject a contribution of mine) to inexperienced open source maintainer (who struggled to determine the worthiness of a pull request) and now to a, hopefully, more understanding contributor and maintainer (who can help steer folks into being good open source contributors, and understands why other maintainers may reject my pull requests). I’d like to share some tips I’ve learned so far:

1. Understand When to Make a Pull Request
2. Communicate Meta Info
3. Communicate Nicely
4. Be Willing to Revise Your Work
5. Follow the Project’s Standards
6. Prefer Small, Backwards-Compatible Changes

Real Life Analogy

Imagine we’re talking about something more familiar than software. Imagine you’ve got a ton of junk in your garage (bicycles, lawn mower, and a few power tools) so you start building a simple shed to store it all. While you’re taking a break, some stranger comes along and, without saying anything, attaches a sky light window to the roof. This wasn’t in your plan, and you don’t really want one: it’s unnecessary, lets burglars see inside, and will be more work to maintain. So you ask the stranger for clarification, but he barks back how he’s a professional builder and you should be grateful for his contributions, then storms off. When you come to, you’re not sure of anything better to do with his work, so you throw it away.

Pretty absurd behavior, right? Yet that’s what frequently happens in open source projects. Strangers submit a pull request with no discussion about why the feature helps, or why this is the best implementation, or grasping the project’s purpose and nuanced complexity, and are then unwilling to revise their work and storm off. They may be good developers, but they don’t yet understand how to contribute to open source. Don’t be one of those people!

Understand When to Make a Pull Request

Open source maintainers usually prefer you write companion software that extends their project, rather than modify the core project itself. In WordPress that means creating a plugin, and in Event Espresso that means creating an add-on (a special plugin that Event Espresso with extra features). WordPress’ policy is to first create a plugin that extends WordPress, and then consider adoption into WordPress core (read more here).

At first, I didn’t understand this; I thought the bigger the project the better. But actually less code is usually better. E.g., there are always new versions of PHP being released, so you should be updating your PHP code to work with the latest version. All code requires maintenance and so the more code a project has, the more work it is to maintain, the more places there could be bugs, and the more difficult it becomes to add other features. Another way to say that is “All code is technical debt“. So maintainers actually want to keep their projects as small as possible, and still have their projects be useful. So unless your code contribution is really useful, they’d probably prefer to keep it out of their core project.

As an example, code that goes into WordPress core should be useful to 80% of WordPress users, otherwise, it should go into a plugin. This keeps the software from becoming bloated with features and options that make it unusable. So just because your code contribution is cool, or even useful to you, it doesn’t mean it will necessarily a good fit for inclusion in the core project. You’re best off first making a plugin, and if it becomes popular, it will be a candidate for integration into the core project.

Communicate Meta Info

My first pull request for the BuddyPress Docs plugin was basically a disaster: I gave absolutely no description of its purpose or why I felt it merited being in the core project instead of being a separate plugin, I didn’t discuss its implementation with the project maintainer whatsoever, and not so surprisingly it wasn’t accepted. The maintainer, Boone Gorges still handled our interactions very courteously and gave some of the credit for his implementation of the feature to me, but my contribution could have been much better. It lacked some critical meta information. I didn’t mention:

So when making a pull request, be sure to mention:

• what the pull request achieves
• how it benefits 80% of users
• why you chose that implementation.

Without any of that information, a project maintainer needs to guess. Or if they’re busy (which they all are), they should probably close your pull request until that information is provided.

Communicate Nicely

Many open source project maintainers are volunteers, so they are under no obligation to continue maintaining it, or to accept your pull request, or to even justify why the pull request was rejected. You are entitled to nothing. They’re only maintaining the project and considering your pull request because it somehow makes them feel good. So if you’re being rude and making them feel bad, they probably won’t give your pull request much thought.

What if maintainers are employed? It’s basically the same situation: they probably have a million other things to do, so if your pull request is a nuisance, they’ll shut it down.

I’ve both dealt with pull requests by entitled contributors and been the entitled contributor. It helps a lot to be gracious.

On the flip side, if a project maintainer dismisses your contribution without much explanation, don’t take it personally. It’s hard for project maintainers to close pull requests expeditiously, but if it’s a busy project that’s what they need to do. If not, they’ll drown in a sea of partially-addressed pull requests and probably end up burning out.

More recently, I’ve started to show more appreciation for project maintainers, and I think it has helped (see this plugin review I left and the subsequent feature request). With regards to WordPress plugins like Event Espresso, you can show your appreciation by at least leaving a positive review in the plugin repository. If your business depends on it, or at least would be very inconvenienced if it weren’t maintained anymore, it’s also in your interest. That’s at least what I’m trying to do, and I think it has encouraged project maintainers to be more receptive to my contributions.

Be Willing to Revise Your Work

At Event Espresso, features go through quite a lot of steps and revisions before they’re released, so don’t expect your pull request to necessarily be accepted first try. We first create a ticket in CodeBase for the feature, plan it out with other team members, a developer creates an initial implementation, it gets reviewed by a second developer and it gets revised, it goes for testing by another team member, and is probably revised again, and will likely be revised some more after its initial release. Don’t expect your pull request to totally bypass all that work, just because you did it.

What’s more, the more popular the project and the more individuals with interests in it, it’s very hard to consider all the different use-cases, server environments, and related features. Daniel Bachhuber once lamented that working with WordPress core was 90% bureaucracy and only 10% coding, whereas his smaller WP-CLI project was just the opposite. Nobody likes bureaucracy, but it’s necessary for big projects, so be prepared for it.

Follow the Project’s Standards

Most open source projects have coding standards that should be followed when making contributions. These help to keep the project organized, even if you think your way of writing code is better. For example, Event Espresso has coding standards (partially based on WordPress’ coding standards, although ours are adopting as much of the PSRs as feasible). Accepting a pull request means the project’s maintainers have decided to adopt it into the codebase they maintain, it becomes their responsibility, and they are the ones who will need to answer for its quality. So it needs to be written in the way they will be able to work with it, otherwise, it won’t get accepted. (Well, or it may just stay in limbo until a project maintainer is able to basically rewrite your pull request following the project’s standards.)

Prefer Small, Backwards-Compatible Changes

Pull requests which add or change a lot of code require more testing and consideration than small ones. With any change, regression testing needs to be done to make sure it doesn’t break other related features. Adding automated unit tests helps there, too.

But if you want to get a pull request accepted, try to keep the changes small. For WordPress plugins, it’s usually best to only add filter and action hooks, and then create a separate plugin that uses those hooks to add your feature. Adding these hooks requires far less regression testing and so are much more easily accepted.

Also, make sure those changes are backwards-compatible (meaning they shouldn’t break anyone’s companion software). We didn’t clarify that as a formal policy before, and it caused unnecessary headaches for everyone involved.

Contributing to Open Source is Worth It!

So making quality pull requests for open source software requires you to understand that if the feature can be done in companion software (a plugin for WordPress, an add-on for Event Espresso) using existing actions or filters, it’s better to do that than make a pull request. And if the actions or filters required for that don’t exist, make a small, backwards-compatible pull request to add them.

When making pull requests, it helps to communicate its purpose and be willing to consider if there might be better ways to implement it. Try your best to follow the project’s standards, and not get irritated when things take a bit more discussing and revising than your personal projects. Open source projects require more collaboration because remember, it not only needs to work for your objectives and site configuration but the objectives of all other software users on all their myriad of site setups.

From my experience, developing software in isolation is quicker, but simply won’t be as good. Contributing to open source software takes some adjustments and has a bit of a learning curve, but when it finally works out, it’s pretty cool to know you’ve improved something used by millions of people (e.g., search for “Mike Nelson” on this WordPress release!). I hope these tips help you adjust to the surprisingly different world of open source collaboration.

What have you learned from collaborating on open source software? Please share in the comments.