New project repo basics
You’re about to start a new open source project, so you create an empty repo. Before you start writing any code, what do you fill it with? You need to define the basic parameters of your project. I’ve created a sample repository with some really basic examples. Let’s take a look.
README.md
Most web-based code forges render the repository’s README file, which makes it a de facto home page. This is a great place to give the basic information about your project. Perhaps most importantly, it says what your project is and who it’s for. This information is woefully missing from so many projects. Let people know if they’re interested in your project or not.
Project README files typically contain instructions for building or installing the software. If the instructions are simple, you can include them in their entirety. If they’re complicated, cover the basic case and refer to a separate file with more details. The README file also gives brief references to other important information covered in the sections below.
LICENSE.txt
Your project isn’t an open source project without an open source license. The LICENSE.txt file should contain just the license text. There’s not much else to say here.
CODE_OF_CONDUCT.md
These days, enlightened projects have a code of conduct. Like with a license, it’s better to use an existing one than to write your own. Once again, there’s not much else to say on this topic.
CONTRIBUTING.md
This file describes how to contribute to the project. You’ll want to include information on how to file a bug report (or not!). If you have particular labels or other metadata practices, include usage information here. (But you probably don’t want to have labels specified this early, as I’ve written.) The CONTRIBUTING file should also include style guidelines for code and docs (although you may need to refer to an external file if the guidelines are lengthy), requirements for submitting pull requests, and so on. My example file includes the project’s goal for replying to pull requests. While not a requirement, it helps to set expectations.
The CONTRIBUTING file also includes the places your project communicates. If you have separate places for certain types of conversations (e.g. development and docs), make sure to clearly communicate those here.
GOVERNANCE.md
All of the files I’ve described so far are pretty standard. This last one isn’t as widely adopted, but it should be. The GOVERNANCE file describes how the project is governed. It lists who leads the project, how those people are selected, and how they make decisions. You should also include how the broader community participates in the decision-making process.
When writing this, avoid the temptation to be overly-legalistic. You’re not writing the full legal code for a country, you’re explaining how a group of people work together. If you’re looking for examples that are more expansive than my quick example, check out the GOVERNANCE file for NodeJS and Kubernetes.
