Maintainer Checklist

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.

Name, Description, Tags

We'll start with the natural beginning for evalutating an OSS project: The descriptive fields that github provides.

It should have a relvant name.
It should have a clear description that tells you what the project does and what it's for.
It should have relevant tags highlighting its scope/stack/field etc.

You may find this trivial, but 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.

A good open source description

Docs, Docs, Docs,

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:

The README - 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:
- A more detailed description of the project than the description field in Github
- How To Install/Run your application or a link to document that explains that
- A link to the code of conduct
- Project status, roadmap, and any other pertinent details for those interested in using or contributing to the app
The Code of Conduct - The code of conduct (usually 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 behaviour in the readme.
The Contributing Guide - 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:
- How to install and run the application, the more detailed the better
- What is the recommended process for making issues/submitting pull requests
- What to do if you feel like somebody is violating the Code of Conduct
- How to communicate with maintainers? How often should you expect interactions/reviews and through what mediums.
A License - 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.
Issue and Pull Request templates - 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.

Templates

Beginner Friendliness

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.

Call to action - Some repositories say "contributions welcome/beginner friendly" in the README or have tags on issues like, just for beginners. Either way, there needs to be some indication that they do in fact, want someone to help.
Healthy interactions With contributors - If this project isn't new, it likely has some history of contributions from other people. Looking at those interactions and how the maintainers work with contributors is a great way to get the "vibe" of the project. How often to maintainers respond? How do they respond? Are people appreciated for their work?
Clear tagging system in issues. The easier it is to navigate the project issues and resources, they more friendly it is for new contributors.

Note that everyone has a slightly different defintion of "beginner friendly", so the experience may vary in different repositories.

Final Thoughts

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.

The Official Checklist

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 at least have most of them.

Additional Resources

The Guide to Building Open Source Communities Introduction to Open Source

Name, Description, Tags
Docs, Docs, Docs,
Beginner Friendliness
Final Thoughts
The Official Checklist
Additional Resources

Name, Description, Tags​

Docs, Docs, Docs,​

Beginner Friendliness​

Final Thoughts​

The Official Checklist​