Quick Ways to Start Contributing to Open Source Projects

Sometimes it's hard to know how to get involved in open source. What follows are more concrete ideas than "write some docs".

Make error messages actionable

Error messages are usually an after-thought for developers and are usually very difficult to parse. Find common errors and give user-friendly output, with options on how to fix it.

Help Others Get Started

Sometimes, setup is complicated. Improve the docs for people installing the project for the first time. Do it yourself and write down all the steps. Then start using the project and write down all the options. Save people time. Redux has great docs

Make the Readme Awesome

If the setup docs are already awesome, make sure the rest of the readme is good too. A good readme should:

  1. Have a simple one sentence summary. Homebrew: ":beer: The missing package manager for OS X." or jsonview: "A Firefox extension that helps you view JSON documents in the browser".
  2. Show install instructions. There should be an step-by-step guide on how to install. This can be as simple as npm install express, or more complex for projects like Bud that might need to be compiled.
  3. Provide a bare minimum example to use. Debug does a good job of this. It's as simple as providing a small snippet of code or command to run to get basic functionality out of your project.

Readmes are good, sites are better

Make a site for the project. gh-pages makes it easy to host a static site. The aptly-named gh-pages package makes it easier.

Sites are a good place to provide a logo and screen-shots of the project in use. You can even start with a pretty version of the readme.

Even better, give a way to try the project. Make a runnable example. If there isn't one, the project needs it. If there is one, is it easy to run? Is it easy to change options? Babel does an excellent job of this, but it's easy to setup any module with Tonic.

Add a license

If the project doesn't have a license of some kind, there are people (mostly at large corporations which have lawyers) who will not be to use the code! It can be a political debate to add a license to a project, but it's easy to do.

There are many options, but the MIT license is very popular. I prefer the Artistic License 2.0 which is a slight variant. Just copy and past the text of the license into a LICENSE file (no extension), and submit a pull request.

Add a changelog

Every project should have a changelog, but many don't. It's a bit tedious to go back through the commit history and create one, but most projects will welcome the change. Especially if you include a script to keep the changelog up-to-date in the future.

Help out on the issues

Look for an issue where someone is asking for help and see if you can reproduce the same problem. If you can, that's great! Post your error message. If you can't, that's great! Post your setup and say you can't reproduce.

Provide Alternatives

If you like the project, or if you don't, the docs could always use a section listing its alternatives and why this project is better/worse. (I've done this on my own projects.)

Quick Ways to Start Contributing to Open Source Projects

Joey Baker


I write code most days. Prevously: photojournalist, EMT. Somewhat obsessed with jouralism.