Hey!
So, you're new to open source, or an open source project maintainer or just curious to know why you need a contribution guide in your open source project. Allow me to describe a scenario, then go ahead with the topic.
You see, contribution guides are the house rules of an Open Source Project.
Imagine you get an Airbnb, in a family house. You have a work trip, or just travelling for a few days, so you require a place to stay. Well, you get a family house with a spare room. Although they have put out one room to house you as a guest, they'd still have some house rules they'd need you to follow, and flouting that might lead to unsavoury circumstances. For example; ensure you don't walk around barefoot, use the in-house slippers or socks, wash your dishes after every meal, etc.
Now, use that same scenario and imagine anyone from anywhere just joined any project because it is 'open' without guidelines, or the proper tools to help you participate better. The result would be chaos.
And that's what contribution guides help you avoid.
Introduction
Contribution guides give you a proper rundown of what a project is about, what tool they use, what kind of contributions are expected in a project, how to make these contributions, who to contact in case you have questions, how to join the community, etc. It is like your “handbook to being a part of a community 101”.
In this article, I list out some very important reasons why a contribution guide is an important part of any open-source project’s success.
Let's get to it.
Reason One – Welcoming New Contributors.
New contributors to your project are like baby birds. They're still learning to fly, and are unsure how best to fit in.
Your contribution guide is one of the best ways to hold their hands and let them know they are welcome in your community. Some qualities of a good contribution guide:
The tone is welcoming.
The article is unassuming of the contributor's experience level.
It contains the skills your community projects are built on or currently need.
It has information on how to contribute to the project.
It also contains information on which communication tool is used in the open-source organisation and how to access it.
Furthermore, it contains people to reach out to in case you need help.
For beginners in a new project, some things that are sometimes understated are:
knowing that a project is what they can contribute to with their current skill set.
knowing what they'd need to learn to be able to contribute effectively while feeling welcomed.
These are some core reasons why an open-source organisation can be considered sustainable, or inclusive.
Open-source organisations, which are conscious of how first-timers interact with their organisation or project and act on them, end up creating healthy and welcoming communities for these contributors.
Reason Two – Ensuring Quality Contributions
This is a direct follow-up from reason one. You cannot have quality contributions if your contributors are confused about what/how to contribute.
Properly educating your first-time contributors, and sometimes even existing members of your community who need refreshers, on the best way to contribute, would help you have better contributions, which would in turn help the PR reviewers and maintainers when they have to look through the contributions made.
They also give your contributors confidence that they are not walking blindly, and are making valuable contributions to the community.
Reason Three – Ensuring, and Encouraging Consistency
Open source projects are “open” to people to contribute. There are no particular restrictions, and people from all over the world can contribute at whatever skill level they currently are at, or are willing to learn.
That is the appeal, and while that is a blessing, sometimes it could also be a disaster if not handled properly. This is why encouraging consistency in your projects is very helpful.
This article by Conventional Commits helps provide more details and guides contributors on making better commit messages, so contributions can easily be grouped and identified.
Reason Four – A Reference Point/Guidebook
Whether you're a first-time contributor or a seasoned contributor to a project, sometimes you might need a reference point to remember how something is done in your community.
Having a detailed contribution guide that is readily accessible helps you have something to look at to help clear a confusion, or act as a guide.
The importance of this cannot be overstated.
Reason Five – Building Healthy Inclusive, and Sustainable Communities
There's an old saying “happy wife, happy life”. While I genuinely do not have any opinions to give on that as that is beyond the scope of this document, I'd like to adapt that saying for open source contributors to “Happy contributors, healthy, and sustainable open source communities”.
When you make your project welcoming and make newbies' first-hand interactions with your project one where they feel included, properly guided and not flustered, it gives them a positive experience about your community and helps them feel like a part of it.
This experience would transcend the first interaction, and would be the reason why your project would have consistent contributors, long-term contributors – and since good experiences sell by word of mouth – there'd also be more people joining the project to contribute to it because of what they've learned.
Summary
It seems like a lot of work, but it is very doable, and also essential that open-source projects and communities be very mindful and conscious of the interactions potential contributors have with them, especially first-time interactions.
Open source projects are hard enough to navigate, as a community, but having a contribution guide that’s understandable and useful to newbies, ensures your open source projects’ community is welcoming and exciting.