| LICENSE |
License |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
All repositories, whether private or public, must include authorship and copyright information. By default, work done by federal employees is not subject to copyright protections under Title 17 U.S. Code Sections 101 & 105, unless for security or contracting purposes. |
| SECURITY.md |
Security & Responsible Disclosure Policy |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This outlines the Security & Responsibility Disclosure policies including vulnerability submission, etc. |
| README.md |
Project Description |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This should be 1-3 sentence short description of the project that can be used as a 'one-liner' to describe the repo. A best practice is using this same language as the official 'description' on a GitHub repo landing page. |
| About the Project |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This should be a longer-form description of the project. It can include history, background, details, problem statements, links to design documents or other supporting materials, or any other information/context that a user or contributor might be interested in. |
| Project Vision |
$\color{blue}\large{\textsf{R}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
This should be a forward-looking statement that outlines the desired future state or long-term goals of the project. |
| Project Mission |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
This should be a statement that defines the purpose, scope, and specific objectives of the project. |
| Agency Mission |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
Agency-led projects should include information about their agency mission. This should be taken directly from agency websites or wikis. |
| Team Mission |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
Agency-led projects should include information about the team executing on the mission. This should be taken directly from internal team charters and functional statements. |
| Core Team |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This information helps with succession planning and provenance for security compliance and remediation. It helps future users and contributors understand where the code originated. |
| Documentation Index |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This is a like a 'table of contents" for your documentation. Tier 0/1 projects with simple README.md files without many sections may or may not need this, but it is still extremely helpful to provide "bookmark" or "anchor" links to specific sections of your file to be referenced in tickets, docs, or other communication channels. |
| Repository Structure |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Using the "tree" command can be a helpful way to generate this information, but, be sure to update it as the project evolves and changes over time. |
| Development and Software Delivery Lifecycle |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Tier 1: Even if the lifecycle is "one-time release" being explicit is better than implicit. |
| Local Development |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Use step by step instructions to get from 'zero' to 'running code.' Should include any system libraries or packages that are a 'pre-requisite' to installation of your project. When possible, including install instructions for multiple Operation Systems (or being explicit about which operating system the project was developed on) is a recommended practice. |
| Coding Style and Linters |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section outlines best practices contributors should follow to reduce friction and improve readability, functionality, and quality of contributions to a project. Oftentimes, these checks can be automated and run as part of a continuous integration and deployment pipeline. |
| Branching Model |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Even for Tier 0/1 projects with one or a few contributors, branching models (such as git flow) are still recommended as a best practice for keeping feature development history clear, and to help reinforce development best practices. |
| Contributing |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
For projects that accept contributions, point towards the CONTRIBUTING.md file. For those that do not (tier0/1) not recommended to include this section, instead, mention one-time release, or private repo status instead. |
| Codeowners |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Though all tiers have an 'implied' code-owner, since there is at least one author of the repo, explicit is better than implicit. In the case that a project may outlive the employment or contract of the original author, a shared inbox or alias is recommended for longer-lived projects (e.g. opensource@cms.hhs.gov). |
| Community |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
For projects that are higher tier than a one-time release, pointing your contributors towards wherever your community exists (e.g. email lists, online discussion boards or channels, project backlogs and documentation, etc...). |
| Community Guidelines |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Project tiers above one-time release should point towards a CODE_OF_CONDUCT.md file or website providing information around acceptable conduct and reporting mechanisms and escalation strategies. It is better to have these processes defined before they are needed, so you can focus on support if/when there is an incident (e.g. Contributor-covenant.org). |
| Governance |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
Make a short statement about how the project is governed (formally, or informally) and link to the GOVERNANCE.md file. |
| Feedback |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Direct users towards the channel where they're encouraged to provide feedback, typically a github.com/$REPO/issue/new URL . |
| Glossary |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
Even for early-tier projects, this documentation can be extremely valuable. Good candidate content includes any project-specific acronyms (esp applicable for Government projects) and any critical Subject Matter Expertise related vocabulary for people who are new to the domain your project is within. |
| Policies |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section is to explicitly link to Federal policies and guidelines that are required or recommended for Federal projects to comply with, such as Accessibility (508) Interoperability, Anti-deficiency, Security, Licensing, and other policies that can vary between agencies and domains. |
| Public Domain |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
A best practice is to list the LICENSE under which a project is released at the bottom of the README. In most cases for Federal repos, we default to Creative Commons Zero 1.0 International (world-wide public domain). |
| CONTRIBUTING.md |
How to Contribute |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Basic instructions about where to send patches, check out source code, and get development support. |
| Getting Started |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Often includes installation steps, pre-requisites for installation, and instuctions for working with the source code. |
| Team Specific Guidelines |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section helps contributors understand any team structure in the project (formal or informal.) Encouraged to point towards the MAINTAINERS.md file for further details. |
| Building dependencies |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This step is often skipped, so don't forget to include the steps needed to install on your platform. If you project can be multi-platform, this is an excellent place for first time contributors to send patches! |
| Building the Project |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Be sure to include build scripts and instructions, not just the source code itself! |
| Workflow and Branching |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
If your project has a preferred workflow or branching structure, mention it here. We recommend 'git flow' as a good default. |
| Testing Conventions |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Discuss where tests can be found, how they are run, and what kind of tests/coverage strategy and goals the project has. |
| Coding Style and Linters |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
HIGHLY ENCOURAGED. Specific tools will vary between different languages/frameworks (e.g. Black for python, esliint for JavaScript, etc...) |
| Writing Issues |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Make a brief statement about where to file issues, and conventions for doing so. Link to ISSUE_TEMPLATE.md file. |
| Writing Pull Requests |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Make a brief statement about where to file pull/merge requests, and conventions for doing so. Link to PULL_REQUEST_TEMPLATE.md file. |
| Reviewing Pull Requests |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Make a brief statement about how pull-requests are reviewed, and who is doing the reviewing. Linking to MAINTAINERS.md can help. |
| Shipping Releases |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
What cadence does your project ship new releases? (e.g. one-time, ad-hoc, periodically, upon merge of new patches) Who does so? |
| Documentation Updates |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Where is the documentation hosted? How is it updated? Who updates it? |
| Policies |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section is here to explicitly link to Federal policies and guidelines that are required or recommended for Federal projects to comply with, such as Accessibility (508) Interoperability, Anti-deficiency, Security, Licensing, and other policies that can vary between agencies and domains. |
| Public Domain |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section is to explicitly link to Federal policies and guidelines that are required or recommended for Federal projects to comply with, such as Accessibility (508) Interoperability, Anti-deficiency, Security, Licensing, and other policies that can vary between agencies and domains. |
| MAINTAINERS.md |
Maintainers |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Who are the project maintainers? List out @USERNAMES where possible so they can be tagged in issues/PRs directly. |
| Maintainers List |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
What groups/domains are maintainers a part of? Does your project have domains/areas that are maintained by specific people? List @USERNAMES directly, or any @ALIASES for groups/teams. |
| Approvers List |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Who are the project approvers? List out @USERNAMES where possible so they can be tagged in issues/PRs directly. |
| Reviewers List |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Who are the project reviewers? List out @USERNAMES where possible so they can be tagged in issues/PRs directly. |
| GOVERNANCE.md |
Governance |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
Starting at Tier 3 GOVERNANCE.md has basic language about early community governance, how the project make decisions, and how contirbutors are elevated through the leadership process if any (e.g. joining teams, getting maintainer status, etc...) |
| CODEOWNERS.md |
List of Users |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Who are the points of contact in your project who are responsible/accountable for the project? This can often be an engineering or design manager or leader, who may or may not be the primary maintainers of the project. |
| List of Repo Domains by Owner |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{blue}\large{\textsf{R}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
e.g. Frontend, Backend, Documentation |
| COMMUNITY_GUIDELINES.md |
Principles |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section communicates to prospective contributors and users what the values of your community are. The examples provided in the template were established by the Justice40 project at USDS. |
| Community Guidelines |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section communicates specific norms and guidelines for how to participate and contribute positively to your community. The more explicit you can be about behaviors you'd like to encourage or discourage, the less friction new contributors will experience in onboarding and operating within your project. |
| Acknowledgements |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section recognizes previous work and best practices established by the other members of the federal open source community such as USDS, GSA, 18F, and the Justice40 Project. |
| CODE_OF_CONDUCT.md |
Contributor Code of Conduct |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
Project tiers above one-time release should include a CODE_OF_CONDUCT.md file or website providing information around acceptable conduct and reporting mechanisms and escalation strategies. It is better to have these processes defined before they are needed, so you can focus on support if/when there is an incident. (e.g. Contributor-covenant.org) |
| Acknowledgements |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{lightcoral}\large{\textsf{N}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
$\color{green}\large{\textsf{M}}$ |
This section recognizes previous work and best practices established by the other members of the federal open source community such as USDS, GSA, 18F, and the Justice40 Project. |