How to improve your open source code (7) – Contributor experience
This post was written during my trip through Iceland and published much latern than it was written.
This is the last post which does not deal with code directly, I promise.
When it comes to open source hobby projects, contributions from others are often happily taken. But making the contribution process smooth for everyone does involve some precautions.
In this article I want to summarize how to make a contribution to a project as smooth as possible for all persons involved.
Public code and contributions
I wrote about this before and I want to shortly reiterate on it. “Open” as in open source (or even better: open contributions) is not black-white at all but there are several levels of grey in between, in my opinion.
The more open your code is, the better a contributor is able to contribute. Whether it be discussion, requests, bug reports, bug fixes or even feature implementation or general enhancement. On the other side, though, the more open your code is the less your contributors are “bound” (in a mentally way) to your project. It can happen (and it happened to me) that a contributor stops by for one pull request or issue and then you'll never hear of them. The better the contribution process is for them, the more likely they come back – and how relevant the project is to them, of course.
The contribution process in the rust community (for the Rust compiler itself) is awesome, from what I've heard. This, of course, enhances the “I will come back and give another issue a try” a lot. The contribution process of the nixpkgs project is slightly worse (but still rather good). Sometimes, nobody answers questions you might have for your pull request for several days or even weeks. This does not really make one eager to file another request.
From what I think, github is the “most open” in the sense of “open contributions”. That's not only because of how github works, as other platforms work equally well (gitlab, gitea, gogs, bitbucket) but also because everyone is on github.
If you want to close down contributions a bit, you could host your own instances of gitea or gitlab – contributors can easily open an account for their contribution, though that slight hurdle will make the “casual code dumper” likely go away.
Even “more closed” would be a email-patch-workflow, git supports (and the kernel community uses successfully for years now). In this case, the code is often made available via a web interface like cgit or klaus.
A project should always contain a readme file in its root folder. The readme file is often the first thing a contributor will look at, not only but also because github renders and displays them.
Often, projects contain a
Contributing file where guidelines (or even
rules) are written down on how to contribute. It does not only contain
statements on how code is submitted but also how issues are filed or
requests should be made.
I think it is extremely important to have such an file available, especially if not hosting the code on a site like github, where it is obvious that code is submitted through pull requests and issues are submitted via the issue tracker.
The length of such an file should respect the size of the project itself. If the project contains 10KLOC, one should be able to read the contribution file in less than two minutes, preferably in less than one minute. It should state not only how code should be submitted, but also whether it should conform to some style guide (which itself can be outsourced to yet another file), how to behave in the community, how to write bug reports and also how to file issues (what information must be included).
Handling issues is clearly a way to improve the contributors experience. As soon as a contributor files an issue, she or he should be greeted and thanked for the issue. Take it this way: Someone just invested time to look at your project and cared enough to have a question, try it out or even found a bug. This is truly a cool thing and therefore they should be thanked for this, as soon as you have the time to do so. The Rust community even automated this, but I don't think this would be necessary for a small or medium sized project/community.
So be nice to every one. Nothing is worse than a maintainer that babbles about bad things or insults the contributor because of his or her ideas or ways an issue was proposed to be resolved. Don't ever do this. I've seen issues where the maintainer of the project started rambling about how bad things were (not the project itself but rather its dependencies or even things that had nothing to do with the project itself). I cannot believe that such projects will last long, let alone survive at all. These projects will die.
Also, your ramblings have nothing to do with the issue at hand and even if they do: be kind and humble will most likely be better in every way, right?
In the next part we will finally go back and actually talk code.
What I want to discuss in the next article of this series is code verbosity. I want to make sure how DRY a code actually needs to be and how much abstraction is enough for the sake of understandability and cleanness of code.