Alexandre Teixeira
a0137b47d1
Adapt the agreed maintainer responsibilities and risk-based review policy for the public repository. Add evidence-driven security review, CodeQL triage, release guidance and a discoverable contributing link.
1.6 KiB
Documentation
Repository Markdown is the canonical source for project documentation. A public docs site may be generated from it; avoid maintaining an independent wiki copy unless there is a deliberate future decision to do so.
Where information belongs
| Location | Purpose |
|---|---|
/design |
Product intent, proposals, and accepted decisions (when those paths are used) |
/specs |
Technical contracts and invariants (when those paths are used) |
/docs |
User, developer, architecture, security, deployment, and maintainer guidance |
| Root Markdown | Discoverable entry points and policies |
Keep root documents easy to find:
README.mdCONTRIBUTING.mdSECURITY.mdCODE_OF_CONDUCT.md
Not every named directory exists today; do not invent a parallel documentation store just to match this map.
Updating documentation
When behavior, architecture, a workflow, or its verification requirements change, update the canonical documentation in the same PR when appropriate.
Separate policy from examples: examples may evolve with tooling; changes to role authority, review requirements, or product ownership require an explicit governance decision. Do not introduce a new mandatory approval rule through a checklist alone.
Documentation PRs should link the relevant issue, record what was reviewed (links, commands, or affected features), and avoid publishing private channels, account names, local paths, secrets, or confidential incident details.
For practical examples of review evidence, see the review playbook. For contributor setup and PR requirements, use CONTRIBUTING.md.