3 Simple Guidelines for Contributing

So what drives someone to contribute to an open source project? 95% of the contributions I have received on my various projects are from people who are trying to make one specific thing work for something they are doing.

I think it is awesome that people take the time to contribute, but, to be honest, a lot of the contributions are no help. They are often very specific and rarely are tested (other than manually by the contributer). Even worse yet, some change existing functionality but add no tests or explanation as to why and then expect me to just pull it in and roll on with life.

1. Explain “why” not “how”

I’m amazed at some of the commit messages I see in contributions. People will add a check to see if something is blank? and then make the commit message “Checking if thing was blank?”. Why do we need to check if something is blank? That is what is important. If I want to know how you did it, I’ll look at the code. Believe it or not, but I can read code. I can’t, however, read your mind like Matt Parkman. Next time you craft your commit message, explain why you did something, now how.

2. Test it

This goes a couple ways. If something was failing during “real” use of the code, but no tests were failing, don’t just fix the problem and send a pull request. Add a test (or spec) that shows what was failing and then add the code to fix the problem. If you don’t add the regression test, chances are that fix you added will break in a future release. If the project maintainer has no tests in their project, either don’t use the project or add tests. Adding tests just may inspire the maintainer to learn and fill out the rest of the tests.

If you don’t know how to test the thing you are fixing, ask around. I know I’d be more than happy to help anyone who is wanting to contribute to one of my projects, but is unsure how to test something. Much happier than receiving another un-tested fix that could just be someone’s opinion instead of an actual problem.

3. Make sure it applies cleanly

While you were working on your well-explained, tested contribution, things may have changed upstream. Be sure to rebase or merge in the latest changes. If your contribution is well-explained, tested and merges cleanly, it will only take the maintainer a few minutes to review it, accept it, and release a new version. If it doesn’t apply cleanly, and the maintainer is like me, the commit, no matter how awesome, will most likely sit at the bus stop waiting for a bus that will never come.

Conclusion

I nearly jump out of my seat in excitement when I receive a well-explained, tested contribution that will apply cleanly. Usually, it is less than a day before I release a new version. On the contrary, if any of those three are missing, it is usually weeks or even months.

The reason is not that I didn’t like the addition, but that I have to fill in pieces you missed (and I don’t have a lot of time). If you didn’t explain why, I have to figure that out (if I even can). If you didn’t test it, I have to test it. If it didn’t apply cleanly, I have to fix merge conflicts and copy and paste code around. And, if you didn’t do any of those three, trust me when I say that you will never see me click ignore faster.

I promise you that if you do these three things each time you contribute to a project, your changes will not only get pulled in faster, but you will become a more rounded and skilled programmer.