There are many reasons that may lead you to the decision to run a project in an open source fashion. You might want to make your application code available to public to increase trust, or make it especially easy to distribute your library to increase usage. Another common motivation is to establish a healthy community of contributors around your project, allowing you to solicit feedback, make your project more diverse and maybe also distribute the burden of maintenance.
Contributions are not only about writing code
Before we talk about how to be friendly to contributors, let’s take a quick detour to define what a contribution to an open source project actually is in the first place. Oftentimes, contributing to an open source project seems to be synonym with opening a Pull Request that fixes a bug or adds a feature. To us, it means a lot more than that. Opening an issue about how something does not work for you is a meaningful contribution as well. Proofreading documentation is just as important as writing code. Offering help to localize the project in a different language is a major contribution. Leaving product feedback, both praise and criticism contribute to moving a project forward. So when we talk about a contributor friendly project, we talk about all of these means of contributing, not only about writing code.
Things we try to do in offen/offen
Offen is a fair and lightweight alternative to common web analytics tools. It’s self hosted software and all code is available at the offen/offen repository on GitHub. In this constellation, feedback and participation is especially important for us. In this article we’d like to share what we do to make our repo friendly and welcoming towards any kind of contribution from the community.
Head first in the README, in-depth docs for later
Striking the right balance between a brief introduction and an in-depth introduction is tough. If you have an idea and just want to get started, you don’t want to be bothered to read through detailed setup instructions. But if you have everything up and running, you probably would like to understand the how and the why of the project’s setup at some point.
In offen/offen we are catering both of those needs in different places. For people who just want to get things running as quickly as possible, we have a short intro in our README. More in-depth explanations on the development setup and the application architecture have been collected in a dedicated documentation site for developers.
This setup is also interesting because it will force you, the project maintainer, to answer two important questions: Can you get external contributors to get up and running with your setup in a few paragraphs? Can you also explain the setup and the architecture in-depth to outsiders in a way that it makes sense?
Contribution guidelines that are helpful and friendly
An established and recommended practice is to have a CONTRIBUTING.md file at the root level of your repository that has details about how to contribute to a project. This might seem like a trivial thing to write, but we found in reality it’s a tricky task to come up with something that is both inviting and helpful for potential contributors.
Often times, documents like this focus on what potential contributors should not do: Don’t open a PR without an issue, don’t open an issue without having searched the existing ones. Those are valid points from a project management perspective and also help the contributors themselves manage the repository. However, phrasing all of this as a list of "donts" and "only ifs" exclusively will subconsciously deter people from contributing. What would you prefer: a duplicate issue from time to time, or no issues at all being raised because users are too scared of doing the wrong thing? Also: do not forget to invite people to making non-code contributions as well.
Check our contribution guidelines for an idea of how we approach this. We also have a Code of Conduct that defines the way we'd like to interact with people.
“Boring tech” is accessible
If you want people to contribute code to your project, the choice of the tech you use is a major factor. Trying to make tech choices boring will help contributors to get started quickly, just because it’s already known to work, and also known how to work with.
In our example, Offen is built as a server side application with a relatively complex frontend running in the browser. On the server we chose Go as a language and the Gin framework. Those might not be most exciting choices in tech, but they are optimized for easy setup, robustness and plenty of good documentation. As a contributor, this means that when I run into issues setting up the project, I will likely find answers online soon instead of having to wrangle some custom framework the maintainers came up with themselves.
In our client side application we started out using the great, but slightly esoteric Choo framework, but soon migrated to Preact, just because the React ecosystem (Preact is a lightweight "clone" of React) is so ubiquitous and well-understood by a lot of people. We also do not use any fancy language features, but try to keep things simple so that you don't need to learn about brand new syntax constructs before you can contribute code. Think twice before you add something like TypeScript to a project you want to be accessible. Every additional layer - no matter how great or helpful they are for you who already knows how to use them - will make it harder for others to get started.
This topic also extends to your project's local development setup. The more extra tools you need the less likely it is someone will try to get started setting up your project on their machine. The setup should also work on all major OSes. A lot of people use Windows, some use Linux, many use a Mac, none of them should be left out. For Offen, we decided to use a docker-compose based setup, which gives us a reproducible cross-OS setup without people having to install anything other than Docker. You can check the compose file in our repository to see how that looks like.
Labels make issues discoverable
In case you host your project on a platform like GitHub or GitLab, the repository’s issue tracker will likely be one of the most important ways of interacting with contributors. Writing clear and concise issues that do not require much insider knowledge is one thing, but how do you make these issues discoverable for anyone who wants to contribute to your project? A common approach is to use labels for your issues.
One aspect of labeling issues is conveying information that is specific to your project. What language would you need to be proficient with to work on the issue? Is the issue not related to code, but an ongoing discussion people could participate in?
The other aspect of labeling is the external ecosystem that has evolved around GitHub issues. For example, sites like Up For Grabs allow anyone to search for issues labeled help-wanted across all public repositories on GitHub. Good first issue lets you find issues labeled good first issue that are well suited for beginners. Applying such labels will connect you with others that otherwise wouldn’t know about your project in the first place.
Check the issue tracker of offen/offen to see how we label our issues here.
Alternative means of getting in touch
We use GitHub for hosting our repository, and while this makes both code and issues publicly visible for anyone, having a GitHub account should not be a requirement for contributing to the project. Whenever we solicit feedback or contributions, we try to make it clear that people can also email us (bonus points for providing a PGP key for those who prefer to use one), tweet at us or use Mastodon to get in touch. Just because a service like GitHub or GitLab is free, it does not mean anyone can or wants to create an account with it. Having multiple feedback channels lowers the barrier of entry for anyone who wants to contribute.
What do you do to make your project contributor friendly?
Do you run an open source project that is geared towards creating a community of contributors? What do you do to make it easy for anyone to make meaningful contributions?
Let us know what you do, and also do not hesitate to start contributing your ideas and feedback about Offen. We’d be happy to have you on board.
Written by Frederik Ring
Top comments (0)