| id | DEV-338 | ||
|---|---|---|---|
| title | Give the Repository a Complete Root README | ||
| status | active | ||
| enforcement | manual | ||
| severity | error | ||
| depends_on |
|
A root README that omits what the repository is, where its docs are, or how to run and deploy it forces every newcomer to reverse-engineer the project from source. The one page everyone opens first fails them.
The root README is the first and most-read page in the repository, so it must
tell a newcomer what the project is and how to run it. Where to find the rest of
the docs is the entry-point role DEV-337 already governs (it
links docs/README.md); this rule covers the landing page's own content.
- Open with an H1 title and a short description of what the repository is and does, so a newcomer understands it in one read.
- Include a Setup section covering every environment the project runs in, each as its own subsection: Local (run it on your machine), Stage or Preview (deploy for internal demo and review), and Production (deploy for real use). Where an environment does not apply, say so and why, rather than omitting it.
- Keep the commands and steps truthful and in sync with the project, per DEV-330. A README that lies about how to run the project is worse than one that says nothing.
- Where the repository provides an automated README check, run it before
pushing and enforce it in the pre-push hook or CI. In this repository that is
npm run check:rules, run by the pre-push hook; a repo without such a script verifies these requirements by review instead.
- The README opens with an H1 title and a description of what the repository is
- Its Setup section has Local, Stage or Preview, and Production subsections
- Environments that do not apply are stated as such, not omitted