How To Build A Contributor Friendly Project

Simple steps to ensure productive contributions to your open source project

Kevin Owocki
Jul 19, 2018 · 6 min read

If you want to have an active community of contributors for your Open Source Repo, it’s helpful to make the repo as self explanatory as possible to prevent unnecessary communication problems or barriers to entry for newcomers. In this post, the Gitcoin team has aggregated our experience working on open source to provide you with a few ‘best practice’ tips.

Readme.md basics

It all starts with ‘Why’

Get ’em started

  • Are there any prerequisites to working on this project?
  • What kind of skills or software do will they need to properly contribute?
  • What is the step by step process to properly setting up your project’s development environment?

Additionally, make sure your contributors know how to run tests for the system. Explain what the tests are, why they’re important, and how to conduct them properly.

Formalities

Most README documents give a brief explanation of the contents of the license as well as link to the license document for contributors to find more details.

Optional (but potentially helpful) additions to README doc:

  • Who your core team is and their contact information
  • Easiest ways to get in contact with you & the best time of day
  • General FYI’s such as ‘please ask before spending your valuable time on a PR’

Docker-ize everything

Source: Docker

Traditional virtualization via VMs all you to split up your hardware so that the hardware power can be split and used separately. Docker containers all you to virtualize the OS. This approach allows you to put pieces of code into smaller, more easily transportable chunks that can run practically anywhere Linux is running.

The reason this is so important is because containers will be massively more efficient on your servers than traditional VMs

Documentation

Proper documentation is oil that keeps your repo running smoothly

Documentation Guidelines

One of the most important pieces of documentation centers around code of conduct. Code of conduct rules allow you to set clear guidelines for your open source contributors so they are aware of what is acceptable and unacceptable behavior within your repo. Here is an example.

Another piece of documentation that has proven conducive to efficient work getting completed is defining the use case for the work requested. Giving your contributors some context on how the small piece they are contributing fits into the overall project picture gives them a much better idea of how to proceed.

Furthermore, it is vitally important to include technical details about the specific request. Making sure that the request is spec’d out to the T is essential to ensuring that a piece of work is completed effectively and on-target with what you had in mind.

With this, it is usually safe to include acceptance criteria. Make sure that, from the get-go, your contributors know exactly what an accepted piece of code will look like

Never hurts to add an example of a good contribution. Link to a pull request that was accepted and show your contributors how it’s done.

Document how the project works

To highlight this idea, we’ve included the Gitcoin Bounty Flow diagram below. This flow diagram, featured on our repo, explains the process for how bounties go from ‘open issue’ to ‘submission accepted’ and all the potential routes in between.

Gitcoin Bounty Flow

Documentation such as this flow diagram can help clear up a lot of confusion for contributors and ensure that everyone is on the same page.

Optional info

Market Your Project

Building a low-fi landing page website is the minimum threshold for marketing to potential users. Make sure that your users have some way of finding out about your project other than having to comb through your repo.

Proven Marketing Avenues

In terms of marketing directly to contributors, we believe one of the most effective ways to do that is to post bounties to Gitcoin for issues on your repo. Gitcoin is fast becoming the hub for open source projects to connect with developers, get great contributions, and continually make progress on the project.

Thanks for reading!

Gitcoin

Grow Open Source

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store