Instructions: This template is intended to provide an example of sections to include in a GitHub repository and suggested content for those sections. This README is generally intended to be programming language and framework agnostic, but not all sections will be relevant to every project. You are highly encouraged to add, update, and remove sections based on your use case.
Examples: See below for examples of repositories with comprehensive README files:
| Repository | Description |
|---|---|
| dataviz-project-starter-kit | DataViz starter kit |
| workrise-where-low-wage-workforce | Svelte + Mapbox application |
| dc-rpp-backend | AWS serverless application |
| education-data.urban.org | Django application |
Description of the project and its status (e.g. under active development, archived, etc.).
Links to production/staging sites, related GitHub repositories, additional documentation on Confluence, Box, etc.
Information on accessing any data files that are used in the code.
Instructions for building and testing code locally. This should include information on software or tools that must be installed (e.g. Docker, Node.js, etc.), requisite configurations or access (e.g. AWS CLI access), environment files, etc. If this requires requesting access, include instructions (via links or contact information for the relevant administrators) for doing so.
Instructions for CI/CD and deploying to servers. This should include information on the CI/CD provider (e.g. CircleCI, GitHub Actions, CodePipeline, etc.), configuration files, branches that trigger deployments to environments, and any other information that may be helpful for developers.
Instructions for running tests, updating the test suite, etc.
Information on subdirectories and/or key files in the repository. An annotated directory tree can be helpful here.
Information on the main frameworks or libraries. This should also contain information on any development principles or approaches to keep in mind to understand and/or contribute to the repository. Architecture diagrams can also be helpful here.
Information on the repository license (if public-facing).
Contact information (name, email address, etc.) for individuals maintaining the repository. This should include at least one Urban employee and any relevant external partners.