From a40f12db4cc82c82b3d3b9980fa8506d16861de0 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 09:46:37 +0700 Subject: [PATCH] Add 10 docs (5 runbooks, charter, 4 migration guides) Closes #637, Closes #638, Closes #639, Closes #640, Closes #641, Closes #663, Closes #627, Closes #628, Closes #630, Closes #631 --- docs/evidence/DOCS_GOVERNANCE_CHARTER.md | 41 +++++++++++++++++++ docs/evidence/MIGRATION_GUIDE_BACKLOG_DOCS.md | 8 ++++ docs/evidence/MIGRATION_GUIDE_COMMAND_DOCS.md | 8 ++++ .../evidence/MIGRATION_GUIDE_GLOSSARY_DOCS.md | 8 ++++ docs/evidence/MIGRATION_GUIDE_RELEASE_DOCS.md | 9 ++++ .../RUNBOOK_FAILING_DOCS_CHECKS.md | 9 ++++ .../RUNBOOK_FINISHING_DOCS_PR.md | 9 ++++ .../RUNBOOK_OPENING_FOLLOW_UPS.md | 8 ++++ .../RUNBOOK_RUNNING_DOCS_CHECKS.md | 10 +++++ .../RUNBOOK_UPDATING_INDEXES.md | 5 +++ tests/test_batch_10.py | 28 +++++++++++++ 11 files changed, 143 insertions(+) create mode 100644 docs/evidence/DOCS_GOVERNANCE_CHARTER.md create mode 100644 docs/evidence/MIGRATION_GUIDE_BACKLOG_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_COMMAND_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_GLOSSARY_DOCS.md create mode 100644 docs/evidence/MIGRATION_GUIDE_RELEASE_DOCS.md create mode 100644 docs/getting-started/RUNBOOK_FAILING_DOCS_CHECKS.md create mode 100644 docs/getting-started/RUNBOOK_FINISHING_DOCS_PR.md create mode 100644 docs/getting-started/RUNBOOK_OPENING_FOLLOW_UPS.md create mode 100644 docs/getting-started/RUNBOOK_RUNNING_DOCS_CHECKS.md create mode 100644 docs/getting-started/RUNBOOK_UPDATING_INDEXES.md create mode 100644 tests/test_batch_10.py diff --git a/docs/evidence/DOCS_GOVERNANCE_CHARTER.md b/docs/evidence/DOCS_GOVERNANCE_CHARTER.md new file mode 100644 index 00000000..0be2d103 --- /dev/null +++ b/docs/evidence/DOCS_GOVERNANCE_CHARTER.md @@ -0,0 +1,41 @@ +# Documentation Governance Charter + +## Purpose + +This charter defines how documentation is governed in the OpenAMP Foundry project. + +## Principles + +1. **Truthfulness first** — documentation must not overclaim. +2. **Single source of truth** — `docs/evidence/METRICS_CURRENT.md` is authoritative for metrics. +3. **Freshness** — documents should be reviewed on a regular cadence. +4. **Accessibility** — documents should be findable from PROJECT_INDEX.md. +5. **Accountability** — every document has an owner (maintainer or designated reviewer). + +## Document Types + +| Type | Description | Review Cadence | +|------|-------------|----------------| +| Policy | Rules and governance | Every 6 months | +| Guide | How-to instructions | Every 3 months | +| Reference | Factual documentation | Every 6 months | +| Concept card | Short explanations | Annually | +| Runbook | Step-by-step procedures | Every 3 months | + +## Change Process + +- **Minor changes** (typos, formatting): Direct commit to main or PR with `minor` label. +- **Major changes** (new policy, restructuring): Standard PR with full review. +- **Urgent fixes** (safety, accuracy): Immediate fix + 24h review. + +## Roles + +See `docs/evidence/DOCS_ROLE_DEFINITIONS.md` for role descriptions. + +## Related Documents + +- `docs/evidence/DOCS_MINOR_EDIT_POLICY.md` +- `docs/evidence/DOCS_REVIEW_CADENCE_POLICY.md` +- `docs/evidence/DOCS_RETIREMENT_POLICY.md` +- `docs/evidence/DOCS_ESCALATION_POLICY.md` +- `docs/evidence/DOCS_EXCEPTION_POLICY.md` diff --git a/docs/evidence/MIGRATION_GUIDE_BACKLOG_DOCS.md b/docs/evidence/MIGRATION_GUIDE_BACKLOG_DOCS.md new file mode 100644 index 00000000..2981a050 --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_BACKLOG_DOCS.md @@ -0,0 +1,8 @@ +# Migration Guide: Backlog Docs + +When moving items from backlog to active or completed: + +1. Update `docs/research/NEXT_100_PR_MAP.md` if the item was there. +2. Update `docs/research/ROADMAP.md` with the new status. +3. If the work was completed, ensure all related docs are updated. +4. Close the corresponding GitHub issue with a link to the PR. diff --git a/docs/evidence/MIGRATION_GUIDE_COMMAND_DOCS.md b/docs/evidence/MIGRATION_GUIDE_COMMAND_DOCS.md new file mode 100644 index 00000000..ad461a07 --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_COMMAND_DOCS.md @@ -0,0 +1,8 @@ +# Migration Guide: Command Docs + +When CLI commands change, update: + +1. `docs/getting-started/COMMAND_SURFACE.md` for command workflows. +2. `docs/evidence/EXIT_CODE_REGISTRY.md` if exit codes changed. +3. Any runbooks that reference the old command. +4. QUICKSTART.md if the change affects demo commands. diff --git a/docs/evidence/MIGRATION_GUIDE_GLOSSARY_DOCS.md b/docs/evidence/MIGRATION_GUIDE_GLOSSARY_DOCS.md new file mode 100644 index 00000000..8684c1af --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_GLOSSARY_DOCS.md @@ -0,0 +1,8 @@ +# Migration Guide: Glossary Docs + +When terms change or new terms are added: + +1. Update the glossary entries in the relevant docs. +2. Check PROJECT_INDEX.md for cross-references to the old term. +3. Run `python scripts/check_doc_links.py` to catch broken references. +4. If a term was removed, add it to the deprecation notice. diff --git a/docs/evidence/MIGRATION_GUIDE_RELEASE_DOCS.md b/docs/evidence/MIGRATION_GUIDE_RELEASE_DOCS.md new file mode 100644 index 00000000..40cd7c0f --- /dev/null +++ b/docs/evidence/MIGRATION_GUIDE_RELEASE_DOCS.md @@ -0,0 +1,9 @@ +# Migration Guide: Release Docs + +When preparing a release, ensure these docs are updated: + +1. `docs/evidence/METRICS_CURRENT.md` — update benchmark numbers. +2. `docs/research/ROADMAP.md` — update completed items. +3. `docs/evidence/SIMULATION_BENCHMARK.md` — update gate verdict. +4. `docs/review/PUBLICATION_PACK.md` — complete checklist. +5. `README.md` — update version references. diff --git a/docs/getting-started/RUNBOOK_FAILING_DOCS_CHECKS.md b/docs/getting-started/RUNBOOK_FAILING_DOCS_CHECKS.md new file mode 100644 index 00000000..5bca16d7 --- /dev/null +++ b/docs/getting-started/RUNBOOK_FAILING_DOCS_CHECKS.md @@ -0,0 +1,9 @@ +# Contributor Runbook: Failing Docs Checks + +If a docs check fails in CI: + +1. Read the error message — it tells you which check failed and why. +2. Run the check locally: `python scripts/check_doc_links.py` or `python scripts/safety/check_claims.py`. +3. Fix the issue (broken link, overclaiming language, etc.). +4. Re-run the check locally to confirm. +5. Push the fix — CI will re-run automatically. diff --git a/docs/getting-started/RUNBOOK_FINISHING_DOCS_PR.md b/docs/getting-started/RUNBOOK_FINISHING_DOCS_PR.md new file mode 100644 index 00000000..6850d89e --- /dev/null +++ b/docs/getting-started/RUNBOOK_FINISHING_DOCS_PR.md @@ -0,0 +1,9 @@ +# Contributor Runbook: Finishing a Docs PR + +Before marking a docs PR as ready: + +1. Run `python scripts/check_doc_links.py` — 0 broken links. +2. Run `python scripts/safety/check_claims.py` — no overclaiming. +3. Run `python3 -m pytest -q` — all tests pass. +4. Verify any new docs are linked from PROJECT_INDEX.md. +5. Request review from a maintainer. diff --git a/docs/getting-started/RUNBOOK_OPENING_FOLLOW_UPS.md b/docs/getting-started/RUNBOOK_OPENING_FOLLOW_UPS.md new file mode 100644 index 00000000..957c0923 --- /dev/null +++ b/docs/getting-started/RUNBOOK_OPENING_FOLLOW_UPS.md @@ -0,0 +1,8 @@ +# Contributor Runbook: Opening Follow-Up Issues + +If your PR uncovers a separate issue that needs attention: + +1. Open a new issue describing the problem. +2. Link the new issue to your PR in a comment. +3. In your PR description, note that follow-up work is tracked in the new issue. +4. Do not scope-creep your current PR — focus on the original task. diff --git a/docs/getting-started/RUNBOOK_RUNNING_DOCS_CHECKS.md b/docs/getting-started/RUNBOOK_RUNNING_DOCS_CHECKS.md new file mode 100644 index 00000000..c6d0768e --- /dev/null +++ b/docs/getting-started/RUNBOOK_RUNNING_DOCS_CHECKS.md @@ -0,0 +1,10 @@ +# Contributor Runbook: Running Docs Checks + +Before submitting a PR, always run: + +```bash +python scripts/check_doc_links.py # check for broken links +python scripts/safety/check_claims.py # check for overclaiming language +``` + +Fix any issues before requesting review. diff --git a/docs/getting-started/RUNBOOK_UPDATING_INDEXES.md b/docs/getting-started/RUNBOOK_UPDATING_INDEXES.md new file mode 100644 index 00000000..3ee43435 --- /dev/null +++ b/docs/getting-started/RUNBOOK_UPDATING_INDEXES.md @@ -0,0 +1,5 @@ +# Contributor Runbook: Updating Indexes + +After adding a new document, update PROJECT_INDEX.md. +After removing a document, remove its entry from PROJECT_INDEX.md. +After renaming a document, update its entry in PROJECT_INDEX.md. diff --git a/tests/test_batch_10.py b/tests/test_batch_10.py new file mode 100644 index 00000000..840ef390 --- /dev/null +++ b/tests/test_batch_10.py @@ -0,0 +1,28 @@ +"""Tests for batch of 10 docs.""" +from pathlib import Path + +FILES = [ + "RUNBOOK_UPDATING_INDEXES.md", + "RUNBOOK_RUNNING_DOCS_CHECKS.md", + "RUNBOOK_FAILING_DOCS_CHECKS.md", + "RUNBOOK_OPENING_FOLLOW_UPS.md", + "RUNBOOK_FINISHING_DOCS_PR.md", + "DOCS_GOVERNANCE_CHARTER.md", + "MIGRATION_GUIDE_COMMAND_DOCS.md", + "MIGRATION_GUIDE_RELEASE_DOCS.md", + "MIGRATION_GUIDE_GLOSSARY_DOCS.md", + "MIGRATION_GUIDE_BACKLOG_DOCS.md", +] + + +def test_all_exist(): + for f in FILES: + path = Path("docs/evidence") / f if "RUNBOOK" not in f else Path("docs/getting-started") / f + assert path.exists(), f"Missing: {f}" + + +def test_each_has_content(): + for f in FILES: + path = Path("docs/evidence") / f if "RUNBOOK" not in f else Path("docs/getting-started") / f + text = path.read_text() + assert len(text) > 50, f"{f} too short"