Open Source projects embody trust, collaboration, and ownership, enabling us to build better solutions faster and give back to the community. With such unique value, though, come some unique requirements.
The strength of Open Source lies in the contributors. Their input may vary from additions to the code or documentation with pull requests to bur reporting and holding discussions through issues. One thing is for sure, though: the easier it is for them to find your project and become engaged in its development, the faster and more striking your solution’s growth becomes.
Having that in mind, we’ve prepared 5 tips on making the repository of your Open Source project more contributor friendly for both new maintainers & users.
Keep README informative but concise
When you get yourself a new device, do you read the instruction manual? Impatience often makes us skip this part altogether. However, taking time to see how things work can save us hours of frustration later – especially when the manual is practical, concise, and straightforward. In this regard, Open Source projects are no different and should also come with a user-friendly introduction: a brief yet informative README file.
A README is usually the first document that contributors see and go through. Serving as an introduction to and the means to jumpstart the Open Source project, it should provide a clear description of the problem statement, the solution, and the installation. By explaining what a given solution does and what it takes to get started, README helps contributors decide whether they’d like to engage in this particular project.
Source: https://github.com/callstack/react-native-testing-library/blob/main/README.md
The onboarding experience is one of the key factors determining the library’s success. As there’s no better way to get acquainted with a new project than through practice, a contributor-friendly README should be highly actionable. You can make this happen by:
- adding basic examples of how to use the library and making sure they’re copy-pasteable for contributors' convenience,
- making code snippets runnable so that things work smoothly,
- specifying the public API and how to use it to avoid confusion.
A README file is also a good place to link to any migration or troubleshooting guides. They can tremendously help your users with common issues to be encountered when upgrading to the newer version of your library or when using it in a specific manner. A nice way to structure your troubleshooting guide is through Frequently Asked Questions (FAQ). As a maintainer, you’ll sooner or later identify those in the issue tracker. You can put FAQs as headers in a markdown file, making the questions linkable and saving yourself some time when answering the same question repeatedly by simply leading users straight to the answer.
In addition to giving contributors a brief project introduction in README, you might also want to create separate documentation. While the former contains succinct technical guidelines, the latter would give more in-depth explanations on things like architecture or elaborate setup. For many users, it’s also easier to navigate a website instead of loosely linked Markdown files on GitHub. Documentation may be considered a nice-to-have, but at the end of the day, it all boils down to the complexity of your Open Source project.
Set expectations within contributing guidelines
Once contributors get through the why behind your Open Source project, they’ll be interested in the how. That’s where the CONTRIBUTING file steps in.
At the highest level, contributing guidelines should explain what’s needed from the setup perspective to start contributing. They also define what makes a good contribution, e.g., a well-formatted pull request or a useful issue, saving both the repository owner’s and contributors’ time and effort.
Much like an effective README, user-friendly contributing guidelines should incorporate lots of examples. This makes the document more relatable and decreases the chances of misinterpreting purely theoretical recommendations.
Source: https://github.com/callstack/repack/blob/main/CONTRIBUTING.md
There are a couple of ways to make contributing guidelines even more helpful for developers working on your Open Source project. One of them is formulating the guidelines as a practical step-by-step contribution article and keeping the examples in a copy-pasteable format. Another is keeping the recommendations inviting and encouraging, but focusing not only on dont’s but also on dos. Last but not least, you might want to go for human-readable naming like houses, groceries, or animals instead of abstract foo, bar, or baz when demonstrating concepts like variables or functions to keep things more relatable.
Bad:
Better:
Make start easier for newcomers
As a core maintainer, you’re likely a skilled developer with many years of coding under your belt. But everybody’s a beginner at some point, and so were you. You needn’t forget about it because newbies will contribute to your OSS project as well – and there’s no point in making their life harder.
A great way to ensure a smooth start for any user is to employ good defaults within your Open Source project. This frees the contributors from the burden of having to configure a given tool or library on their own, which may be a dealbreaker, especially for regular users. A zero-config setup allows them to dive deep into the project straight away, making common things easy and hard things possible.
Optimize work on issues with labels and descriptions
Work organization has a big impact on how the software project unfolds, and OSS is no exception. As your Open Source project grows, so does the list of issues in the repository. To keep things contributor-friendly and optimize the workflow, you might want to pay special attention to how issues are labeled and described.
Labels categorize issues according to various criteria, including but not limited to the nature of the issue, its priority, or the level of complexity. For example, every new GitHub repository comes with a pre-defined set of labels that you can edit to fit your project and contributors’ needs better. The key thing is to keep your labeling clear and relevant, especially in new releases.
Source: https://github.com/callstack/react-native-paper/issues
There’s one label we’d like to discuss in greater detail: good first issue. This label marks issues well-suited for newcomers and is a win-win for both freshly-minted contributors and repository owners. For the former, it's removing barriers to future contributions; for the latter, it’s making an Open Source project more discoverable.
As this article focuses on providing a good contributor experience, we suggest you pay special attention to explaining and documenting your project’s good first issues thoroughly so anyone can pick it up easily. You might also want to dedicate extra time to supporting and empowering first-time contributors, which we’ll discuss in greater detail later.
Source: https://github.com/callstack/reassure/issues?q=is%3Aissue+label%3A%22good+first+issue%22+is%3Aclosed
Another thing to keep in mind is to describe issues in a way that makes it look like a well-scoped task, not an overwhelming problem. Shedding light on the context, elaborating on the issue itself, proposing the next steps, or tagging relevant people – all while staying short yet descriptive – have the potential to foster collaboration and push your Open Source project forward.
Be nice and offer support to contributors
Open Source is made possible thanks to collaboration. Among developers working on your OSS project, there’ll be more and less experienced individuals. While members of this community will most likely support each other, you, as the core maintainer, should consider putting effort into making them move forward.
Sharing your experience, providing guidelines, and offering code reviews will be particularly appreciated by newcomers, but showing empathy and being responsive are the building blocks of a positive contributor experience for all developers. It may sound obvious, but we all enjoy working in a safe and encouraging environment, don’t we? After all, the human side of the Open Source is more important than any README or CONTRIBUTING file, so why not make it a nice one?
Final thoughts
At Callstack, we build the Open Source culture through encouragement and the OSS Maintainers program that allows developers to spend dedicated time solely on maintaining the projects they care about. We like to say that Open Source is in our DNA, and we really mean it. In fact, the idea for this article was a result of one of our monthly meetings, during which we exchange knowledge and experiences in the repositories we take after.
Sharing is caring. We believe giving back what we learned and sharing with others is important – the same way as developers before us shared their code, time, and effort with us so we could learn.
We hope this article inspired you to make your OSS repo more contributor friendly. Big thanks to all who took part in the R&D Maintainers meeting that led to its creation: Adam Trzciński, Jakub Binda, Łukasz Walczak, Maciej Jastrzębski, Natalia Gros, and Satyajit Sahoo.
Check out our Open Source libraries, and let’s contribute to the React and React Native ecosystems together!
