Improve collaboration through community health files

Whether you are an open source project maintainer or just starting to contribute on your first project, community health files in the project repository can set you up for success. Community health files are quickly becoming the de-facto way to provide open source users and collaborators with extra context surrounding open source projects.

A community health file is...

At the most basic level, any file that exists in a repository and provides valuable information to someone using or contributing to your project can be considered a community health file.

For example, a CONTRIBUTING.md file in your project could describe how to set up the project to run the tests when submitting a new patch.

But let’s take that definition a little further and require that the filenames and locations be standardized.

So community health files are:

A standard set of files that provide additional context, help, and safety to users or collaborators within your open source project.

Context

Let’s use CONTRIBUTING.md as an example again. Any project can be someone’s first open source contribution. So even if our project has an easy setup process before someone can contribute, we should still provide setup instructions somewhere in the repository. And if someone is going to be contributing to the project, the first place they are going to check is in a file labeled CONTRIBUTING—it’s right there in the name. 😉

This file can also contain other context to reduce back-and-forth about how a patch can be submitted! For example, a specific format for commit messages.

Help

Community health files can also be used to help users, contributors, and you. By supplying an ISSUE_TEMPLATE.md file, everyone will know which information is necessary for you to triage an issue that’s submitted. Users will be able to provide all the relevant information which will reduce your workload and turnaround time on the fix. It’s a win-win for everyone involved!

Safety

Community health files should also be used to create a positive space for people to contribute. By having a CODE_OF_CONDUCT.md in your project, you are making everyone aware that they are expected to behave in the manner stated, setting an expectation that your project will be inclusive, and being clear that contributors will be subject to the enforcement policy outlined if they don’t.

This sets common expectations for everyone participating and ensures no one is “above the law” on the project.

Tooling

By using a set of standardized filenames, different systems are able to provide a set of tooling that surface contextual information to users.

For example, Tidelift can detect and populate your Release Notes based on a CHANGELOG.md file or detect your Coordinated Disclosure Policy in your SECURITY.md file. Of course, we let you configure this, but using the standard names allows you to rely on our defaults and for non-Tidelift users to find the information within your project.

Other systems may display information from your community health files inline or special tabs within their user interface. On GitHub, the SECURITY.md file is displayed in the “Security” tab!

Use them today!

Community health files aren’t just reserved for mature, well-established projects. You can ensure your users and contributors have the info they need to be effective by adopting them today. Feel free to reach out with questions in our forums as you start implementing these. We are here to help!