During the OpenStack summit a few weeks ago, I had the chance to talk to some people about my experience running open source projects. It turns out that after hanging out in communities and contributing to many projects for years, I may be able to provide some insight and an external eye to many of those who are new to it.
There are plenty of resources explaining how to run an open source project. Today, I would like to take a different angle and emphasize what you should not do in your projects. This list comes from various open source projects I have encountered in past years. I'm going to go through some of the bad practices I've spotted, illustrated by some concrete examples.
Seeing Contributors as an Annoyance
When software developers and maintainers are busy, there's one thing they don't need: More work. To many people, the instinctive reaction to external contribution is—damn, more work. And, actually, it is.
Therefore, some maintainers tend to avoid that surplus of work. They state they don't want contributions or they make contributors feel unwelcomed. This can take a lot of different forms, from ignoring contributers to being unpleasant. They avoid the immediate need to deal with the work that has been added on their shoulders.
This is one of the biggest mistakes and misconceptions of open source. If people are sending you more work, you should do whatever it takes to make them feel welcome so they continue working with you. They might soon become the guys doing the work you are doing instead of you. Think: retirement!
Let's take a look at my friend Gordon, who I saw starting as a Ceilometer contributor in 2013. He was doing great code reviews, but he was actually giving me more work by catching bugs in my patches and sending patches I had to review. Instead of being a bully so he would stop making me rework my code and reviews his patches, I requested that we trust him even more by adding him as a core reviewer.
And if they don't do this one-time contribution, they won't make it two. They won't make any. Those projects may have just lost their new maintainers.
Letting People Only Do the Grunt Work
When new contributors arrive and want to contribute to a particular project, they may have very different motivations. Some of them are users, but some of them are just people looking to see what it is like to contribute—getting the thrill of contribution as an exercise or as a willingness to learn, then start contributing back to the ecosystem they use.
The usual response from maintainers is to push people into doing grunt work. That means doing jobs that have no interest, little value, and probably no direct impact on the project.
Some people actually have no problem with it, while others will. Some will feel offended to do low impact work and some will love it as soon as you give them some sort of acknowledgment. Be aware of it, and be sure to high-five people doing it. That's the only way to keep them around.
Not Valorizing Small Contributions
When the first patch that comes in from a new contributor is a typo fix, what do developers think? Do you think they don't care, or that you're wasting their precious time with your small contribution? And nobody cares about bad English in the documentation, do they?
I contributed to Org-mode for a few years. My first patch to orgmode was about fixing a docstring. Then I sent 56 patches, fixing bugs and adding fancy features and also wrote a few external modules. To this day, I'm still #16 in the top-committer list of Org-mode who contains 390 contributors. So I'm not what you would call a small contributor. I am sure the community is glad they did not despise my documentation fix.
Setting the Bar Too High for Newcomers
When new contributors arrive, their knowledge about the project, its context, and the technologies can vary largely. One mistake people often make is to ask contributors complicated things. That scares them away and they may just disappear, feeling too ignorant to help.
Before making any comment, you should not have any assumption about their knowledge. You also should be very delicate when assessing their skills, as some people might feel vexed if you underestimate them too much.
Once that level has been properly evaluated (a few exchanges should be enough), you need to mentor to the right degree so your contributor can blossom. It takes time and experience to master this and you may likely lose some of them in the process, but it's a path every maintainer has to take.
Mentoring is a very important aspect of welcoming new contributors to your project, whatever it is. I'm pretty sure that applies nicely outside free software too.
Requiring People to Make Sacrifices with Their Lives
This is an aspect that varies widely depending on the project and context, but it's important. As a free software project, where most people will contribute on their own goodwill and sometimes spare time, you must not require them to make big sacrifices. This won't work.
One of the worst implementations of that is requiring people to fly 5,000 kilometers to meet in some place to discuss the project. This puts contributors in an unfair position, based on their ability to leave their family for a week, take a plane/boat/car/train, rent an hotel, etc. This is not good, and everything should be avoided to require people to do that in order to participate and feel included in the project and blend in with your community. Don't get me wrong: This does not mean social activities should be prohibited. On the contrary. Just avoid excluding people when you discuss any project.
The same applies to any other form of discussion that makes it complicated for everyone to participate: IRC meetings (it's hard for some people to book an hour, especially depending on the timezone they live in), video conference (especially using non-free software), etc.
Everything that requires people to interact with the project in a synchronous manner for a period of time will put constraints on them that can make them uncomfortable.
The best medium is still e-mail and asynchronous derivative (bug trackers, etc), as it allows people to work at their own pace at their own time.
Not Having an (Implicit) CoC
Codes of conduct seem to be a trendy topic (and a touchy subject), as more and more communities are opening to a wider audience than they used to be, which is great.
Actually, all communities have a code of conduct, being written with black ink or being carried in everyone's mind unconsciously. Its form is a matter of community size and culture.
Now, depending on the size of your community and how you feel comfortable applying it, you may want to have it composed in a document, e.g. like Debian did.
Having a code of conduct does not transform your whole project community magically into a bunch of carebears following its guidance. But it provides an interesting point you can refer to if needed. It can help throwing it at some people, to indicate that their behavior is not welcome in the project and, somehow, ease their potential exclusion.
I don't think it's mandatory to have such a paper on smaller projects. But you have to keep in mind that the implicit code of conduct will be derived from your own behavior. The way your leader(s) will communicate with others will set the entire social mood of the project. Do not underestimate that.
When we started the Ceilometer project, we implicitly followed the OpenStack Code of Conduct before it even existed, and probably set the bar a little higher. Being nice, welcoming and open-minded, we achieved a decent score of diversity, having up to 25 percent of our core team being women—way above the current ratio in OpenStack and most open source projects!
Making non-English Speakers Feel like Outsiders
It's quite important to be aware that the vast majority of free software projects out there are using English as the common language of communication. It makes a lot of sense: It's a commonly spoken language and it seems to do the job correctly.
But a large part of the hackers out there are not native English speakers. Many are not able to speak English fluently. That means the rate at which they can communicate and run a conversation might be very low, which can make some native or fluent English speakers frustrated.
The principal demonstration of this phenomena can be seen in social events like conferences where people are debating. It can be very hard for people to explain their thoughts in English and to communicate properly at a decent rate, making the conversation and the transmission of ideas slow. The worst thing that one can see in this context is an English native speaker cutting people off and ignoring them, just because they are talking too slowly. I understand that it can be frustrating, but the problem here is not the non-native English speaking. It's the medium being used that does not make your fellow on the same level of everyone by moving the conversation orally.
To a lesser extent, the same applies to IRC meetings, which are relatively synchronous. Completely asynchronous media do not have this flaw, and that's why they should also be preferred in my opinion.
No Vision, No Delegation
Two of the most commonly encountered mistakes in open source projects are (1) seeing the maintainer struggling with the growth of its project while (2) having people trying to help.
Indeed, when the flow of contributors starts coming in and they are adding new features and asking for feedback and directions, some maintainers choke and don't know how to respond. That ends up frustrating contributors, who then may simply vanish.
It's important to have a vision for your project and communicate it. Make it clear for contributors what you want or don't want in your project. Transferring that in a clear, unaggressive manner is a good way of lowering the friction between contributors. They'll soon know if they want to join your ship or not and what to expect. So be a good captain.
If they chose to work with you and contribute, you should start trusting them as soon as you can and delegate some of your responsibilities. This can be anything that you used to do from reviewing patches targeting some subsystem, to fixing bugs and writing docs. Let people own an entire part of the project so they feel responsible and care about it as much as you do. Doing the opposite, which is being a control freak, is the best shot at being alone with your open source software.
And no project is going to grow and be successful that way.
In 2009, when Uli Schlachter sent his first patch to awesome, this was more work for me. I had to review this patch, and I was already pretty busy designing the new versions of awesome and doing my day job! Uli's work was not perfect, and I had to fix it myself. More work. And what did I do? A few minutes later, I replied to him with a clear plan of what he should do and what I thought about his work.
In response, Uli sent patches and improved the project. Do you know what Uli does today? He manages the awesome window manager project instead of me. I managed to transmit my vision, delegate, and then retire!
Non-Recognition of Contributions
People contribute in different ways and it's not always code. There are a lot of things around a free software projects: Documentation, bug triage, user support, user experience design, communication, translation….
It took a while for Debian to recognize that their translators could have the status of Debian Developer. OpenStack is working in the same direction by trying to recognize non-technical contributions.
As soon as your project starts attributing badges to some people and creating classes of different members in the community, you should be very careful that you don't forget anyone. That's the easiest road to losing contributors along the road.
Don't Forget to be Thankful
This whole list has been inspired by many years of open source hacking and free software contributions. Everyone's experience and feeling might be different or malpractice may have been seen under different forms. Let me know if there are any other points that you encountered and blocked you to contribute to open source projects!