A handy checklist for Open Source maintainers!
This document is a short and simple guide to help you determine if a GitHub repository is a good fit for contributing to open source. We highlight key areas and considerations to help you evaluate whether or not you want to contribute to an open source project.
This also doubles as our very own guide for Virtual Coffee-endorsed Open Source projects.
We'll start with the natural beginning for evaluating an OSS project: The descriptive fields that GitHub provides.
These are first and most straightforward way GitHub uses to recommend your content to potential contributors.
Also, if you're looking to particpate in Hacktoberfest, adding the
Hacktoberfest tag to your repo description is one especially important way to indicate that.
At the end of the day, all we know of a project before we start it is what we say and what the maintainer tells us. Having good documentation is the best indicator that a project is well maintained, well supported, and has a healthy and active community. There are a plethora of materials a repo can utilize to provide context to potential contributors, but the docs that matters most are:
This is the face of your repo. It's the first thing anyone sees, after maybe the name and description, and it's the nexus for all content, links, docs, and other project associations. A project without a README is probably not ready for accepting contributions. Some basic things you should include in your README are:
🔎 Here is VirtualCoffee.io's current README
The code of conduct (often referred to as the COC) is an excellent indicator of healthy contributor's environment. There are many Code of Conduct styles online and many projects use one of the standard templates (which is fine). But it's always worth taking a look at a project's Code of Conduct before starting any contribution work. Not every OSS project may necessarily have one though; some maintainers opt to simply describe appropriate behavior in the README.
Last but certainly not least, there should be some discussion of how to contribute to the project. Some folks write these instructions directly in the README which can be alright, but we prefer an explicit document that highlights:
There are many popular and vetted open source licenses that make it easy and safe for people to contribute to a particular project. It is not advised to work on a project without that doesnt have a license, or is not using one of these.
🔎 Here is VirtualCoffee.io's current License
These are templates that provide a guide for potential contributors on make issue and pull requests respectively to the project. They remove a lot of burden from the maintainer and the contributor one trying to guess the appropriate procedure for these contributions.
Ultimately, if you're looking for a repository/project that is beginner friendly, they should have some indication in the documentation and processes that highlights that.
just for beginners. Either way, there should be some indication that they do want someone to help.
Note that everyone has a slightly different defintion of "beginner friendly", so the experience may vary in different repositories.
There are many other things that can help make a repository feel more welcoming, like demos, video guides, etc., but this document is meant to address the minimum requirements. When Virtual Coffee determines the projects we highlight and recommend to our members, these are the things we look for and why. Hopefully, it can serve as a guide to anyone who finds this document.
Here's the checklist in plain form based on the guide above. It isn't necessary for a project in the wild to have all of these things, but it should have most of them.
hacktoberfesttopic should be placed in the project description, or the
hacktoberfest-acceptedlabel added to accepted pull requests