Avoiding bad practices in open source project management

12 readers like this.
People arranged in the shape of FOSS


During OpenStack Summit Austin, I had the chance to talk to some people about my experience on 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 hindsight 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 out there. Today, I would like to take a different angle and emphasize what you should not socially do in your projects. This list comes from various open source projects I encountered these past years. I'm going to go through some of the bad practices I have spotted, in a random order, illustrated by some concrete examples.

Seeing contributors as an annoyance

When software developers and maintainers are busy, there is one thing they don't need: more work. To many people, the instinctive reaction to external contributions 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 make contributors feel unwelcome. This can take a lot of different forms, from ignoring them to being unpleasant. It indeed avoids the immediate need to deal with the work that has been added on the maintainer's 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 feel them welcome so they continue working with you. They might pretty 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 review 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 how it is to contribute. Getting the thrill of contribution, as an exercise, or as a willingness to learn and 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, some have. 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 is 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? That they don't care, that you're wasting their precious time with your small contribution. And nobody cares about bad English in the documentation, do they?

This is wrong. See my first contributions to home-assistant and postmodern: I fixed typos in the documentation.

I contributed to Org mode for a few years. My first patch to Org mode 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, which contains 390 contributors. So I would not call that 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 of the mistakes people often make is to ask contributors too-complicated things that they cannot realize. That scares them away (many people are going to be shy or introverted), and they may just disappear, feeling too stupid to help.

Before making any comment, you should not have any assumption about their knowledge. That should avoid such situations. 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 your contributor so he or she can blossom. It takes time and experience to master this, and you may likely lose some of them in the process, but it is a path every maintainer has to take.

Mentoring is a very important aspect of welcoming new contributors to your project, whatever it is. I am pretty sure that applies nicely outside free software, too.

Requiring people to make sacrifices with their lives

This is an aspect that varies a lot depending on the project and context, but it is really important. As a free software project, where most people will contribute on their own good will 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 a 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 your community. Don't get me wrong: that 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 is 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 basically 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 media are still email and asynchronous derivatives (bug trackers, etc.), as they are asynchronous and allow people to work at their own pace on their own time.

Not having an (implicit) Code of Conduct

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, 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 as soon as you need to. 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, even if nobody wants to go that far generally, and that it is rarely that useful.

I don't think it is 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% of our core team being women—way above the current ratio in OpenStack and most open source projects!

Making people who are not native English speakers feel like outsiders

It is 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 is 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 people frustrated, especially native English speakers.

The principal demonstration of this phenomenon can be seen in social events (e.g. 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 do understand that it can be frustrating, but the problem here is not the non-native English speaking, it is 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, that is why they should also be preferred, in my opinion.

No vision, no delegation

Two of the most commonly encountered mistakes in open source projects: seeing the maintainer struggling with the growth of its project, while having people trying to help.

Indeed, when the flow of contributor starts coming in, adding new features, asking for feedback and directions, some maintainers choke and don't know how to respond. That ends up frustrating contributors, who therefore may simply vanish.

It is 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 (and non-aggressive, please) manner is a good way of lowering the friction between contributors. They will pretty 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: reviewing patches, targeting some subsystem, fixing bugs, 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 staying 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 since 2010 instead of me. I managed to transmit my vision, delegate, and then retire!

Non-recognition of contributions

People contribute in different ways, and it is not always code. There are a lot of things around a free software project: documentation, bug triage, user support, user experience design, communication, translation…

It took a while, for example, 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 is 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 experiences and feelings might be different, or malpractice may have been seen under different forms. Let me know if there are any other points that you encountered that blocked you from contributing to open source projects!

User profile image.
Principal Software Engineer at Red Hat, working on OpenStack Telemetry. Free Software hacker for 15+ years, Emacs and Debian developer. Author of The Hacker's Guide to Python.


I am a deaf software developer.

One day I volunteered to contribute to a Free Software project, in which people used weekly conference calls to discuss the project.

The conference calls were not accessible to me. The participants did not even bother to make discussion summaries available to me.

Few weeks later I withdrew from the project.

Moral: make the means of communication accessible to people with disabilities. This comes in addition to accommodations for people who are not native speakers of the project's language, and people who do not hold on their own in synchronous discussions.

And, know when to let go.

The PhpWiki project, which I launched in December 1999, is still active today and probably in large part because I stepped down as the project manager and let others take over.

It was actually hard for me to do because I was so attached to the project and the success it had; but I wasn't contributing anything anymore and had lost the zeal for new features and new releases. I am much prouder today because the project still lives!

Let me just say to each of your above recommendations, "Amen Brother!" And hope the language doesn't drive other readers or commenters away. :)

I helped write the FreeBSD bylaws, both the election rules and the original code of conduct, more than a decade ago. These relatively simple rules and agreements have been amended and updated, but have pretty well stood the test of time for a very large and very active project. We had grown large enough by the early 00's to have recognized that docs people were critically important to the success of FreeBSD, including the people who carefully translated the Handbook into 20 or more different languages, as well as the giant throng of contributors that port applications to FreeBSD (largely from Linux). FreeBSD has continued to be a thriving community partly because it formed into teams to accomplish different parts of the work, and the "official" project recognized this.

Here is the current FreeBSD Code of Conduct: https://www.freebsd.org/internal/code-of-conduct.html . I believe it largely reflects the points you have made above, and states them succinctly in unequivocally.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.