Contributing to Open Source

Dispelling myths

Documentation is valuable

You don't need to fully understand the project in order to contribute. One of the most common ways to contribute to a project (including Rails!) is by fixing documentation. Fixing a typo in the README or a misleading example in the docs will instantly help everyone who uses the project.

The "beginner's mind" can actually be helpful in improving a project. People who've been using a piece of software for years tend to gloss over flaws, and they don't run into the same problems as someone who's unfamiliar with the software. New people are the ones who need clear documentation and are (happily) in the best position to provide better documentation because they're reading it.

Code changes don't have to be hard

Adding warning messages and better error messages helps everyone, and most projects can benefit from this. For example, Elm has very helpful, human error messages that point at exactly what went wrong. These kinds of messages help the project's public perception and help everyone who's using the project.

Adding warning messages often doesn't require holding the whole project's code in your head -- the messages are specific and local to one or two files, making it easier to grasp the context. Error messages are also a great one to fix as you encounter them.

Maintainers want to help

A lot of people believe that maintainers don't care about their contributions or are too important to help. Usually that's not true: it's in the maintainers' best interest to help contributors. Maintainers want to improve their projects, so they will often work with contributors until the changes can be merged in, practically mentoring you along the way.

Even if you don't know how to solve a problem yet, submitting work in progress can be helpful to maintainers. They can often push the code over the finish line faster than you can, since they have deep experience with the code.

Pull requests are always better than issues, even if the pull request has breaking tests or doesn't quite work. A pull request, even a "broken" one, feels like much less work to maintainers than an issue.

Who can be a maintainer?

Anyone!

An open-source maintainer is anyone with a public repo on GitHub. If people find the code interesting, they will start submitting issues and pull requests, and voila -- a maintainer. Almost every maintainer on GitHub organically became a maintainer.

If a maintainer notices someone who consistently contributes, they'll often grant commit access to make it easier for that contributor and to lessen their own burden. (We've done this many times at thoughtbot.) Now there's more than one maintainer!

Contribute!

How to know what to do?

Finding what to work on is often the first blocker for people. As a new person, you don't have context for a project. To solve this, some organizations tag issues that are good for people new to the project, like "help wanted" or "documentation".

Here are some examples:

• org:thoughtbot is:open label:"help wanted"
• org:doorkeeper-gem is:open label:"help wanted"
• org:railsbridge is:open label:"Beginner Friendly"
• org:18f is:open label:"help wanted"

Meeting new people in events like meetups or conferences, and asking how you can help in the issue tracker, are great ways of finding people with more experience that will help you find next tasks to work on.

Documentation

Blog posts and screencasts about your experiences with a piece of software are really helpful for the community. Other people are searching for them, and if you can provide them, that's absolutely a contribution.

Empathy for maintainers

Typically, maintainers are doing this in their free time, so they may take a few days (or weeks) to respond. If they receive an abrasive issue or an aggressively impolite pull request, they probably won't be motivated to fix that problem. On the other hand, a polite request will lead to collaboration and a better solution for everyone involved. Remember, every additional feature has a maintenance burden.

There's an excellent talk by former thoughtbot developer Elle Meredith about how to talk to collaborators called Feedback Matters (slides are here). It's useful both as someone giving feedback and as a someone receiving feedback, so both sides of the maintainer/contributor relationship.

Practical example

In our Weekly Iteration episode Contributing to Open Source, Step-by-Step, former thoughtbot developer Ben Orenstein works with thoughtbot CTO Joe Ferris to create a pull request for shoulda-matchers. That step-by-step episode covers more of the practical aspects of contributing to open source, including how to fork a repo and how to find the contributing guidelines for a repository. It feels a lot like a pairing session, so it’s quite technical, and has a few general, higher-level tips around contributing

Also check out Tute's book, Maintaining Open Source, for help on growing and maintaining your own open-source project.

thoughtbot's open source projects and contributions

We have launched a dedicated page showcasing our remarkable open source projects and contributions to external initiatives.

Explore the world of thoughtbot's open source endeavors at thoughtbot.com/open-source. While you're there, we encourage you to take a moment to consider contributing to one of our projects!

Let's collaborate and make a difference together in the open source community.