Skip to main content
Recent posts

Why contributor guidelines matter.

Jake Page
Jake Page
Developer Relations Engineer
· 5 min read

Contributor guidelines thumbnail

TL;DR​

As an open-source project maintainer, you should be obsessed with Developer Experience. I don’t need to convince you that the README.md needs to be clear and informative. Everybody knows how great documentation can elevate a project. Having a top-notch CONTRIBUTING.md file is the missing piece to retain the open-source contributors you attract.

The CONTRIBUTING.md file should not be confused with a tutorial or a project guide, it’s reference material for developers who want to understand what work is available and how to get involved quickly.

Make sure your guidelines are:

  • Clear and actionable
  • Use precise language
  • Easy to skim through
  • Point to additional resources

Understand your audience​

Developers are not a monolithic group of internet dwellers who all care about the same problems, have the same experience, or work the same way. Having said that, there are a few things that are broadly applicable. They want to read less and build more. 🏗️

Developers care about getting started quickly and it’s on the project maintainer to remove as many obstacles as possible to make that happen.

How can you reduce the time from when a developer finds your project to when they submit their first PR?

To get started, contributors need to find an issue to work on. Make sure you have open issues ready that are tagged to cater to all potential contributors. If a junior developer wants to learn a new language through your project make sure good first issues are easy to find. If more ambitious, senior types, are ready to make an impact, make sure it’s clear which issues you would like them to consider, pointing them to a current milestone or GitHub project.

Define contribution paths​

Make clear what kind of paths there are to contribute to. Which areas of the project need help? Leverage GitHub tags to segment each project domain. In our case, Glasskube has different components such as a GUI, a CLI and Package Controller, Docs, a UI and the repo itself.

Community engagement​

Ok, so the contributor knows that there are open issues ranging in different levels of complexity and they understand the different areas they can contribute to. How can they let you know they are ready to contribute to the project? What if they have additional questions? Make it clear how you prefer them to communicate with you, through GitHub, Discord, or Slack.

Try to not only limit communication to the GitHub issue itself. For many Open Source contributors the fun is meeting other like minded people to collaborate and share. Not to say they everybody want that, but make sure you invite contributors to a community, since they are not part of it.

Community engagement

Contribution workflow​

Probably one of the most important parts of the Contributor guidelines is for contributors to have clear instructions and answers to the following questions

Detailing the step-by-step process for contributing code changes: 🪜

  • Issue selection and assignment.
  • Forking the repository.
  • Branching, coding, and committing conventions.
  • Pull request submission and review.
  • Handling feedback and iteration.
  • Merging contributions into the main codebase.
  • Addressing best practices for commit messages and keeping forks up-to-date.

Development guidelines​

Each open-source project aims to solve a different problem and build on a certain stack that might be new to some contributors. Assume they know nothing about your tool and precisely explain the project’s building blocks.

Focus on informing how the code base is built, how each component fits together and describing setup environments. Ideally, contributors should be able to build local versions of the components they contribute to and validate their work.

If you only find out during the PR review process that it wasn’t clear to the developer, it's a sign that either the guidelines or collaboration process could be improved.

Testing​

I can’t stress the importance of providing clear instructions for testing code contributions 🧪. For example, Glasskube operates within Kubernetes clusters, every contributor must have access to one for local testing before submitting a PR. While imposing testing criteria might be challenging, it's essential to remind contributors that PR reviews shouldn't be the moment where issues with functionality are discovered.

Documentation and best practices​

Leverage your documentation heavily, the contributor guidelines as mentioned are reference material aimed at giving guidance by pointing the contributor in the direction of the answer they are looking for. 🔍

Keep the file structure very clear. Most people skim through this sort of material looking directly for what they need at the time. Make your guidelines skimmable.

Also, it’s safe to assume some contributors will never make it to your CONTRIBUTING.md page, and those who do will spend a limited amount of time there. Share a TL;DR that gives the main points you would like contributors to remember. Also, add the TL;DR to other places outside of the GitHub repo. I’ve added it to the #help-forum on our Discord server

Best practices

I’m really happy you have a killer README.md file, you have a bunch of well-tagged issues and are ready to welcome as many contributors as possible. But to retain and build trust within your community make sure to nail the CONTRIBUTING.md too.

To understand the value of the CONTRIBUTING.md file. I feel a restaurant analogy might be useful.

💡 We've all been drawn to a restaurant by it’s food menu, only to return for the exceptional service. Similarly, in the realm of Open Source projects, the README.md acts as the initial attraction, the enticing menu. However, it's the CONTRIBUTING.md file and how it enhances the overall developer experience that makes them return for more.