Simple steps to ensure productive contributions to your open source project 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.
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.
A good README document is essential to making sure contributors can easily get started on your open source project.
A lot of solid README docs start off with a quick description about the project and, more importantly, the ‘why’ behind the project. Give your future contributors an general idea for why they should be contributing to your project in particular. At Gitcoin we try to make our ethos as clear as possible; Our mission is to grow open sourceand we’re focused on building the future of web3 and the open source community as a whole.
Next up, make sure your contributors know the quickest way to get started contributing to your project.
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.
In order to remove any potential barriers for contributors to work on your project, it is important to feature an Open Source License in your README document. Open source licenses make it apparent to all parties involved that this software is freely available to be used, modified, and shared.
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:
Docker containers have become hugely popular over the last four years. Dockers are another form of virtualization for running applications.
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
Communicating your expectations from contributors is key to ensuring that work can be completed without many roadblocks.
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.
One of the most useful things you can do in documentation of your repo is to explain 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.
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.
To avoid a lot of unnecessary communication with contributors, you may want to consider defining how and when to follow up on work. Clear guidelines for acceptable communication allow you to avoid bottlenecks and improve the quality of each communication. This can potentially be critical for streamlining a project; especially one with many contributors working at a time.
Properly marketing your open source project is arguably as important as the other points listed above. In terms of who to market to, there are two main parties that you want to get in front; users and contributors.
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.
One of the best ways to publicize your open source project is to be active on Twitter. Some of the most prominent open source projects like to publicize open issues via their Twitter. It’s also a great place to have quick one-off conversations with potential contributors, explain a concept about the project quickly, and herd these potential contributors to your Github repo.
In terms of marketing directlyto 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.
What other examples of great OSS contributor experience have you seen? Leave us a comment below or get in touch on slack and let us know.