At the Sydney Alt.Net group last month we ran an Open Source Hack Night. The idea was to move from being a consumer of open source to being a contributor, to demystify what’s involved in an open source project, talk through some of the dos and don’ts, and the practical steps of getting started. Then we jumped in and did just exactly that over pizza and drinks. It was a fun night.

This is a recap of what we talked about on the night. I’m not going to walk through the mechanics of how to make a contribution, but will list some tips on how to find and get involved in a project and how to be successful at it.

Find a project. Duh!

More and more projects these days have issues that make for good “on-ramps” into the project. The web site http://up-for-grabs.net is an aggregator site for issues that meet this criteria. Have a browse of the projects on the site and see what interests you. Or just look at a project you use in your normal day to day work and see where/how you might be able to help.

Maintainers are people, just like you.

They’re developers with the same time pressures and insecurities that you have. The project they’re working on was likely started to scratch an itch and then made public in the hope it would help others. Remember to interact and treat these people with the same respect that you yourself want to be treated.

Check the social dynamic

If you see a project you might want to contribute to, look through the issues and pull requests to see how open the maintainers communicate and how open they are to contributions and different ideas. Lurk in the chat room (if they have one) and see what the banter is like. If you don’t like what you see, move along.

Contribution guidelines

Read the contribution guidelines if they exist. And follow them! They might be in a readme.md or a contributors.md or on a wiki. If you ignore them don’t be surprised if your contribution is rejected. Pretty obvious, right Smile

Contribute small changes to start with

It reduces the time you spend before getting feedback from the maintainer(s) and they’re easier for maintainers to absorb. A large contribution that you have put a lot of time into only to have it rejected is extremely discouraging and can you off from ever making future contributions. Large contributions also carry a lot more risk for the project making maintainers leery of spending the time to look through if this is your first contribution. Remember that maintainers are just like you. What would you want to see from a new developer making changes in your work projects? Small, incremental changes or massive, cross cutting changes. It’s the same for open source maintainers. They need time to get to know you.

P.S. Check with your employer about making contributions on work time. Unsurprisingly employers expect you to be building the thing they’re paying you to build. You should also check what the rules are for contributing back code to projects you’re using for work. Some employers still have backwater policies about open source and IP protection.

You don’t need to write code to contribute

Documentation is the one thing open source projects struggle with more than anything else. Maintainers would love it if you made documentation contributions. It’s just as critical to adoption as the code is, if not more so. After all, consider how you feel about using an open source project with no documentation versus one that has great documentation. A lot of projects now use https://readthedocs.org/ to host their documentation with the sources in git repositories. It’s easy to help write documentation.

You can also contribute by responding to questions/issues on the project site, on StackOverflow, or on other forum(s). You could also create screencasts, talk about the project at user groups, blog about it or do anything else you can to raise awareness. These are all useful and valuable contributions. Don’t be constrained by thinking it’s all about code.

A counter-example

Let’s learn from a an example of what not to do, shall we? Have a look at https://github.com/aaronpowell/db.js/pull/112 and you’ll see a number of things that have gone wrong here. To make it easier, let me give you a list:

  1. Assuming the maintainer is able to respond immediately to all your requests (12 hours between the posting of the PR and re-asking for it to be merged and then 24 hours until the second request for it to be merged).
  2. Making a large contribution that deals with more than just the issue that needs fixing.
  3. Changing the development tool chain used by the project.
  4. Claiming not to have time to adjust the pull request, but expecting that the maintainer does.
  5. Getting angry with the maintainer for asking for changes to make the contribution easier to absorb.

Yeah. Don’t do this, OK? Great! We’re good to go, then.

 

Want more information?

Need to go a little deeper? Want specific “How To” information or other tips? Check out this selection of posts and articles others have written:

Most of all, dive in! Have a go! We’d love to see you involved. Good luck!