From 273fdcdf1cea2c3a3b99c6d79416c4bff67e8cef Mon Sep 17 00:00:00 2001 From: OpenCode Date: Tue, 7 Jul 2026 12:00:55 +0700 Subject: [PATCH] Add 5 doc governance docs Closes #664, Closes #665, Closes #672, Closes #673, Closes #674 - Role definitions, decision record policy, urgent correction policy, governance FAQ, ops manual index --- docs/evidence/DOCS_DECISION_RECORD_POLICY.md | 23 +++++++++++++++++ docs/evidence/DOCS_GOVERNANCE_FAQ.md | 25 +++++++++++++++++++ docs/evidence/DOCS_OPS_MANUAL_INDEX.md | 18 +++++++++++++ docs/evidence/DOCS_ROLE_DEFINITIONS.md | 21 ++++++++++++++++ .../evidence/DOCS_URGENT_CORRECTION_POLICY.md | 22 ++++++++++++++++ tests/test_doc_governance_batch.py | 21 ++++++++++++++++ 6 files changed, 130 insertions(+) create mode 100644 docs/evidence/DOCS_DECISION_RECORD_POLICY.md create mode 100644 docs/evidence/DOCS_GOVERNANCE_FAQ.md create mode 100644 docs/evidence/DOCS_OPS_MANUAL_INDEX.md create mode 100644 docs/evidence/DOCS_ROLE_DEFINITIONS.md create mode 100644 docs/evidence/DOCS_URGENT_CORRECTION_POLICY.md create mode 100644 tests/test_doc_governance_batch.py diff --git a/docs/evidence/DOCS_DECISION_RECORD_POLICY.md b/docs/evidence/DOCS_DECISION_RECORD_POLICY.md new file mode 100644 index 00000000..752243bf --- /dev/null +++ b/docs/evidence/DOCS_DECISION_RECORD_POLICY.md @@ -0,0 +1,23 @@ +# Documentation Decision Record Policy + +Significant documentation decisions should be recorded for future reference. + +## What Requires a Decision Record + +- Adding or removing a policy document +- Restructuring the documentation directory +- Changing the documentation license +- Adopting or changing a documentation standard +- Retiring a document + +## Format + +Use `schemas/decision_log.schema.json` for machine-readable records. + +## Required Fields + +- `date` — ISO 8601 date +- `decision_type` — one of the schema's allowed types +- `decision` — approved, rejected, or deferred +- `evidence_refs` — links to relevant PRs or discussions +- `reasoning_notes` — rationale for the decision diff --git a/docs/evidence/DOCS_GOVERNANCE_FAQ.md b/docs/evidence/DOCS_GOVERNANCE_FAQ.md new file mode 100644 index 00000000..259c691e --- /dev/null +++ b/docs/evidence/DOCS_GOVERNANCE_FAQ.md @@ -0,0 +1,25 @@ +# Documentation Governance FAQ + +## Who owns the documentation? +The project maintainers own the documentation. Contributors are encouraged to +improve any document that helps them work. + +## How are decisions about documentation made? +Major changes (new policies, restructuring) go through the standard PR and +review process. Minor changes (typos, formatting) can be committed directly. + +## What happens when docs disagree? +`docs/evidence/METRICS_CURRENT.md` is the single source of truth for metrics. +For other conflicts, the most recently updated document takes precedence. + +## Can I add a new document? +Yes. Add it to the appropriate subdirectory under `docs/` and link it from +`docs/PROJECT_INDEX.md`. + +## How do I find the right document? +Start at `docs/README.md` (the front door) or `docs/PROJECT_INDEX.md` +(the exhaustive catalog). + +## Who reviews documentation PRs? +Any maintainer can review documentation PRs. Safety-critical docs require +a safety reviewer. diff --git a/docs/evidence/DOCS_OPS_MANUAL_INDEX.md b/docs/evidence/DOCS_OPS_MANUAL_INDEX.md new file mode 100644 index 00000000..ca256103 --- /dev/null +++ b/docs/evidence/DOCS_OPS_MANUAL_INDEX.md @@ -0,0 +1,18 @@ +# Documentation Operating Manual Index + +This index maps contributor tasks to the documentation they need. + +| Task | Document to Read | +|------|------------------| +| Run the demo | `QUICKSTART.md` | +| Understand limitations | `LIMITATIONS_OVERVIEW.md` | +| Contribute a fix | `CONTRIBUTING.md`, `CONTRIBUTOR_CURRICULUM.md` | +| Create a PR | `RUNBOOK_PICKING_UP_ISSUE.md` | +| Request review | `RUNBOOK_ASKING_FOR_REVIEW.md` | +| Handle review feedback | `RUNBOOK_HANDLING_REVIEW.md` | +| Fix doc links | `check_doc_links.py` | +| Check for overclaiming | `check_claims.py` | +| Understand the architecture | `ARCHITECTURE.md` | +| Find evidence definitions | `EVIDENCE_CERTIFICATE.md` | +| Find benchmark results | `METRICS_CURRENT.md` | +| Prepare a release | `PUBLICATION_PACK.md`, `RELEASE_DRY_RUN_GUIDE.md` | diff --git a/docs/evidence/DOCS_ROLE_DEFINITIONS.md b/docs/evidence/DOCS_ROLE_DEFINITIONS.md new file mode 100644 index 00000000..f2915507 --- /dev/null +++ b/docs/evidence/DOCS_ROLE_DEFINITIONS.md @@ -0,0 +1,21 @@ +# Documentation Role Definitions + +Defines who is responsible for what in the documentation system. + +## Roles + +| Role | Responsibilities | Required For | +|------|------------------|--------------| +| **Contributor** | Fix typos, update examples, add tests for docs | All changes | +| **Reviewer** | Verify accuracy, completeness, and claim wording | PRs with policy changes | +| **Maintainer** | Own doc structure, approve new docs, enforce standards | New document creation | +| **Safety reviewer** | Verify safety docs are accurate and current | Safety policy changes | +| **Project lead** | Own documentation vision and license | Structural changes | + +## How Roles Map to GitHub + +- Contributor = anyone with a GitHub account +- Reviewer = project maintainer or delegated reviewer +- Maintainer = GitHub team with write access +- Safety reviewer = designated safety maintainer +- Project lead = repository owner diff --git a/docs/evidence/DOCS_URGENT_CORRECTION_POLICY.md b/docs/evidence/DOCS_URGENT_CORRECTION_POLICY.md new file mode 100644 index 00000000..289d00b0 --- /dev/null +++ b/docs/evidence/DOCS_URGENT_CORRECTION_POLICY.md @@ -0,0 +1,22 @@ +# Urgent Documentation Correction Policy + +For critical errors that could mislead readers or cause harm. + +## What Qualifies as Urgent + +- Safety policy misstatement +- Incorrect assay protocol +- Overclaiming language about biological proof +- Broken link in a critical path (quickstart, safety policy) + +## Process + +1. Fix the error immediately. +2. Open a PR with the `urgent` label. +3. At least one maintainer must review within 24 hours. +4. After merge, log the correction in the decision log. + +## Post-Correction + +- If the error was present in a released version, issue a correction notice. +- Review what allowed the error to pass review and adjust process. diff --git a/tests/test_doc_governance_batch.py b/tests/test_doc_governance_batch.py new file mode 100644 index 00000000..4a94c2bc --- /dev/null +++ b/tests/test_doc_governance_batch.py @@ -0,0 +1,21 @@ +"""Tests for doc governance docs batch.""" +from pathlib import Path + +FILES = [ + "DOCS_URGENT_CORRECTION_POLICY.md", + "DOCS_GOVERNANCE_FAQ.md", + "DOCS_OPS_MANUAL_INDEX.md", + "DOCS_DECISION_RECORD_POLICY.md", + "DOCS_ROLE_DEFINITIONS.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path(f"docs/evidence/{f}").exists(), f"Missing: {f}" + + +def test_each_has_content(): + for f in FILES: + text = Path(f"docs/evidence/{f}").read_text() + assert len(text) > 100, f"{f} too short"