Night Dreaming (by Sudar)

Last month, I talked about why you should open source your pet project, and also explained, how I started maintaining the Arduino Makefile project.

After that, this past one month has been really busy. I guess instead of me explaining how busy it had been, I guess the following picture would give a better idea.

There were 70+ commits that got into the project and huge number of critical bugs got fixed. If you look very closely, you will also find that it’s not just me who have been doing this 🙂

I always believed that github encouraged contribution to projects, but in the last one month I also learned a couple of new lessons on how you could encourage more participation and contribution to your open source projects.

Below are some of those learnings. Do take them with a pinch of salt though 😉

Let people know that they can contribute

This might seem silly, but it is really important to let people know that your project is open for contribution. I have spent countless hours fixing bugs and sending pull requests to projects in github, only to know that the repo owner is not interested in contribution 🙂 And it is still worse, when they just decide to be silent about it, without even leaving a small comment.

So let people know upfront whether you will be accepting contributions or not. You don’t have to write huge paragraph about it. Just a single line, which says “contributions are welcome” in the readme file should do it. I generally add some variation of the following in my projects.

All contributions (even documentation) are welcome 🙂 Open a pull request and I would be happy to merge them.

Let people know how to contribute

The next thing to do is to let people know how to contribute. The following are things which you might have to let them know.

• Which coding style they should follow
• Tabs vs space or 2 vs 4 character indent or to have a semi-colon or not 😉
• Whether they should open a pull request or send you a patch/diff
• Whether all pull requests should contain test or/and documentation
• How they should word the commit message. I try to follow this guide by Tim Pope
• Whether you need them to have multiple commits or one single commit

You could choose your own process, but keep in mind that the simpler the process the easier it is to follow it. I generally follow a very simple process and reword or change the commit message if needed.

One other thing, you might have to keep in mind is that, not everyone is comfortable with git/github. In those cases, I point them to the guide that I wrote to help people contribute to github projects.

Track feature requests and TODO’s

Sometimes people want to just get their hands dirty by contributing a simple fix or feature before they become comfortable. In order to help people get started I track all feature requests and TODO’s in github issues. I also use TODO comments in the code and if applicable also link it to corresponding github issue. I also add the following line in the readme file.

If you are looking for ideas to work on, then check out the following TODO items or the issue tracker.

In addition to helping people who want to contribute, this also helps me to keep track of issues and features for the projects. If applicable also try to create milestones and assign issues and feature requests to corresponding milestones. This will also be useful for users of your project, to know when to expect a feature to be implemented.

Respond to pull requests

If someone sends a pull requests or reports an issue, try to respond to it. When someone creates an issue or pull request, they have spent their free time and you should respect that fact.

Sometimes you may not be interested in accepting the pull request. In those cases at least let them that you can’t accept it and also let them know the reason why you don’t want to accept it.

Be polite

Eventually, you will receive a pull request which is just plain stupid. Even in those cases try to be very polite.

When people are just getting started they may miss out something and might make mistakes or may not understand something which will look too trivial. But if you are going to embarrass them or be hostile, then it is not going to be helpful for them. They might just stop contributing not just to your project but for any project. Be polite and encouraging, especially if they are just getting started and you might make someone’s day a little brighter 🙂

Also leave a simple “Thank you” comment after you merge someone’s pull request. It is a little mark of respect that you show for someone who has taken an effort to fix your code.

Follow a proper versioning policy

Any project which will be used by more than one person needs a proper versioning. These days I have started to follow Semantic Versioning for most of my projects. It is very simple to use and very effective.

Show people how to do it, by doing it

Whenever I want to contribute to a project, I try to get a sense of how things are done by seeing the commit history. So if you want people to follow a certain process or style when they contribute, then you should follow it in the first place.

Hide your time machine 😉

.. and don’t forget to hide your time machine 😉

Sometimes a little humor in your comment to a issue might make it easy for you to communicate with someone on the other side of the globe.

Happy coding 🙂