Welcoming Communities

posted by Gregor

You don’t build a community. You build a space.Saron Yitbarek

A lot of people enjoy contributing to Open Source projects. And Open Source projects love contributions. And yet I keep seeing newcomers struggling to contribute and project maintainers struggling to find contributors. What’s the catch?

The Hoodie Animals on an open fire

There is a gap. A gap between the desire to contribute to a community and the ability to find one. A gap between what contributions are welcome, and what people think is wanted. A gap between what people wish they could contribute, but don’t know how, or are afraid to try. At the Hoodie Community, we work hard to close this gap. And despite being an independent project with little to no resources, it aspires to be “one of Open Source’s most diverse and inclusive communities.”

The are 3 things we focus on

  1. We reach out to new contributors
  2. We make Hoodie fun
  3. We keep it fun

I. Reach out

A typical Open Source contributor starts out as a user of the software. They find a bug, documentation lacking on a specific point or want a feature to be added, and contribute code through a code hosting platform like GitHub. Others just want to work on a fun project. How can they find yours?

1. Go where your future contributors are

Become part of initiatives like First Timers Only, Your First PR or Up For Grabs. Participate in projects like Google Summer of Code, Rails Girls Summer of Code or Outreachy.

2. Turn contributors into ambassadors

Make the experience a great one, and even one-time contributors will promote your project in the future.

3. Host events

“Meet the Hoodies” is an event series we host wherever we can. It’s simple and people love it. ProTip: invite other projects to join forces. Start small.

4. Share your thoughts

Your project is much more than just code, it tries to solve a problem. Talk about it, write about it. You don’t have to do it on your own, turns out people enjoy contributing editorial work just like you enjoy contributing code.

5. Stickers

People love stickers :)

II. Make it fun — for everyone

You have taken the first hurdle, you’ve gained interest. The immediate questions that decides whether a visitor becomes a contributor or not are:

  • “Is this a safe place?”
  • “Am I good enough?”
  • “Is it worth my time?”
  • “What is the license?”

Some of these might seem obvious, but please keep in mind: this is not about you. What is about you and is in your best interest is to recruit contributors who enjoy and who are capable of doing the things that you are not. Do you enjoy coding, but not answering issues? Then identify those individuals in your community who do and let them have it. This approach works well and goes a long way in minimizing maintainer burnout.

1. Be Safe

It doesn’t matter how fun and amazing your project is, if people don’t feel safe — they won’t contribute. Security is a hygienic factor — make sure it is good enough. You want a Code of Conduct. Contributor Covenant is a great resource for this, but refrain from just copy & pasting. Take a moment and read it, and make sure you document how you will enforce it and be prepared to enforce it. Here is Hoodie’s Code of Conduct.

2. Be Legal

Not only will people refrain from contributing to your project if it lacks a license, but not having one can and will get you in all kinds of trouble. And according to the definition of the term “open source,” your library is not open source if it doesn’t have a license. So choose an Open Source license.

3. Be Inclusive

Use simple language (Hemingway can help). List all professions like “Design”, “Editorial”, “Documentation” instead of saying “Non-Coding”. Use gender-neutral language, prefer “them” and “they” over “him” and “she”. Avoid phrases like “Hey guys”. If you use Slack, you can configure slackbot to suggest alternatives, as we do in our Hoodie Chat. This is your chance to “set a tone” in your community. It helps to limit unfriendly, over-demanding and self-entitled requests from strangers.

4. Lower barriers

It is the process of contributing that is oftentimes the most challenging. Link to Make a Pull Request for Open Source beginners. Optimize for (new) contributors. Avoid excessive guidelines. Less RTFM, more LMFTFY. Less acronyms ;) Split up your code into self-contained, documented modules. For example, the Hoodie Server is made of small modules, new code contributors only need to understand the module they contribute to not the larger project. Require the minimum amount of tools. Invest in good tests and 100% coverage, so you can accept code contributions quickly and with confidence.

5. Dedicate space

“Just look through the open GitHub issues” is a great way to lose a potential contributor. Create a dedicated place for new (and existing) contributors. This is your chance to say what kind of contributions you are looking for, how much they matter, whom to ask for help, mention guidelines, link to open issues, and show what people are currently working on. At Hoodie, we have Hoodie Camp — a place dedicated to Hoodie’s contributors and maintainers.

6. Be welcoming

Imagine you hear about Hoodie for the first time, you are curious and have some time on your hands. And then you see an open issue like this — what is your reaction? Probably something like “Wow. They really put a lot of effort into this”. Which is what we do, and for that exact reason. We want to make it easy for people to contribute and you can do it, too. Before you object, this is a lot of work, but it’s not just about making a lasting first-time impression. It’s about sending a signal to everyone about the importance of helping new contributors, while encouraging new maintainers to review pull requests. This is about creating a community of people who will go out and spread the word about how awesome your project is, which will help you find even more contributors.

III. Keep it fun

It’s one thing to gain new contributors. It’s a whole different story to retain them. Most of your contributors will be volunteers. And that means: as an Open Source project, you are doomed to be fun.

1. Make contributions matter

Once someone’s contribution is ready, probably in the form of a pull request, try to get back to them as quickly as possible. A comment like “Thanks so much! I’ll review this next week” is better than not commenting at all. Once a code contribution gets merged, release a new version as fast as possible. At Hoodie, we automate that process entirely with semantic-release. A new Hoodie version with the new contribution is usually available minutes after the Pull Request is merged.

2. Build relationships

Most communications within Open Source projects are anonymous. It makes a huge difference when your contributors are able to connect, even if it’s through a short video chat. Regular team hangouts are a great way for contributors to meet the people running a project. Something I personally like to do is to invite a new contributor to a spontaneous call, so I can say thank you in person and introduce myself.

3. Turn contributors into committers

A committer can edit code, create branches and manage issues. It’s a sign of trust and an award to be officially invited to become part of the project. You can require that all tests still pass and code coverage remains at 100% before anything can get merged into a master branch. Another integration we like at Hoodie is LGTM — it requires a “LGTM” comment from two members of the maintainers team. And if you use GitHub for collaboration, there are great ways to protect branches, so nothing can (accidentally) be damaged.

4. Turn committers into maintainers

A maintainer’s overarching goal is to maintain and improve the space for contributors. This can mean a lot of things:

a. Respond to issues b. prepare issues for new contributors c. document workflows d. write tutorials e. summarize what happened so more people can follow the progress.

5. Show genuine appreciation

A symbolic award increases the retention rate of new Wikipedia editors by 25% (with a statistically significant effect for a year). An award can be as simple as saying thank you in public. It is powerful. It’s about fostering a culture around appreciation. That’s what we do with regular shout outs at Hoodie, for example. Also check out all-contributors.

6. Be Transparent

Avoid private discussions. All discussions should be documented and made public with enough time for everyone to who cares to comment. Make your processes transparent, e.g. how someone becomes a maintainer. Especially when it comes to money, try to be as transparent as possible. A promising new project to help with that is Open Collective.

7. Scale

Good intentions alone will burn you out. Remember: nobody is entitled to your attention. With that in mind, with more users, you will need more contributors. And with more contributors, you will need more maintainers. I highly recommend to read Mikeal’s Healthy Open Source and Growing a contributor base in modern open source on that topic.

What’s next?

A lot of the work we invest into making Hoodie a welcoming community is manual labor. Finding out who contributed? It turns out it is not so easy, if you care about more than just code. Creating well documented issues for new and existing contributors? It is a lot of copy and paste. And as coders, what do we do when we repeat ourselves? We create tools to automate our chores. In the case of community management however, we shouldn’t automate everything, but we should create amazing tools that help us at becoming better and more efficient.

Imagine if the tools for our communities were as good as for our code. Imagine if we could see how the balance between users, contributors and maintainers evolves over time. Imagine if we could see who contributed something, if it was their first contribution to your project, or to Open Source in general. Imagine if everyone could show appreciation for every contribution.

An issue like this could be created with very little effort. An automated bot could ping maintainers depending of the day and the time. It could automate the workflow from claiming an issue by a new contributor, to starting a pull request, to reaching out to the right maintainers at the right time, to letting the contributor know when the code was released, adding the contributor to the team, giving a shout out, and learning more about demographics of your project. Code is not the challenge of our Open Source communities.

People are.

Let’s put them first.


Thanks to Coraline Ada Ehmke, Jan Lehnardt, Kent C. Dodds and Kim Crayton for their reviews ❤