docs(maintainers): publish governance handbook draft and review playbook

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.
This commit is contained in:
Alexandre Teixeira
2026-10-15 11:16:52 +01:00
parent c74f475679
commit a0137b47d1
10 changed files with 470 additions and 0 deletions
+31
View File
@@ -0,0 +1,31 @@
# 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.md`
- `CONTRIBUTING.md`
- `SECURITY.md`
- `CODE_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](review-playbook.md). For contributor setup and PR requirements, use [CONTRIBUTING.md](../../CONTRIBUTING.md).