From d6db63480edd3097d555e754fd74c71671d07381 Mon Sep 17 00:00:00 2001 From: Abhimanyu Saharan Date: Thu, 12 Feb 2026 13:19:37 +0000 Subject: [PATCH] CI: add markdownlint + docs-check wrapper; extend link check scope --- .github/workflows/ci.yml | 4 ++-- .markdownlint-cli2.yaml | 23 +++++++++++++++++++++++ Makefile | 7 +++++++ backend/templates/AUTONOMY.md | 1 - backend/templates/SELF.md | 1 - docs/03-development.md | 3 +++ docs/README.md | 18 ++++++++++++++++++ docs/coverage-policy.md | 3 +++ docs/deployment/README.md | 3 +++ docs/openclaw_gateway_ws.md | 3 +++ docs/production/README.md | 3 +++ docs/testing/README.md | 3 +++ docs/troubleshooting/README.md | 3 +++ scripts/check_markdown_links.py | 23 ++++++++++++++++------- 14 files changed, 87 insertions(+), 11 deletions(-) create mode 100644 .markdownlint-cli2.yaml create mode 100644 docs/03-development.md create mode 100644 docs/README.md create mode 100644 docs/coverage-policy.md create mode 100644 docs/deployment/README.md create mode 100644 docs/openclaw_gateway_ws.md create mode 100644 docs/production/README.md create mode 100644 docs/testing/README.md create mode 100644 docs/troubleshooting/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 05ee0998..f17053e0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,9 +88,9 @@ jobs: make frontend-build - - name: Docs link check + - name: Docs quality gates (lint + relative link check) run: | - python scripts/check_markdown_links.py + make docs-check - name: Upload coverage artifacts if: always() diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 00000000..301225ec --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,23 @@ +# markdownlint-cli2 config +# Keep the ruleset intentionally tiny to avoid noisy churn. + +config: + default: false + MD009: true # no trailing spaces + MD010: true # no hard tabs + MD012: true # no multiple consecutive blank lines + MD047: true # single trailing newline + +globs: + - "**/*.md" + +ignores: + - "**/node_modules/**" + - "**/.next/**" + - "**/dist/**" + - "**/build/**" + - "**/.venv/**" + - "**/__pycache__/**" + - "**/.pytest_cache/**" + - "**/.mypy_cache/**" + - "**/coverage/**" diff --git a/Makefile b/Makefile index 1cbb6f2e..b64228ff 100644 --- a/Makefile +++ b/Makefile @@ -124,6 +124,13 @@ backend-templates-sync: ## Sync templates to existing gateway agents (usage: mak check: lint typecheck backend-coverage frontend-test build ## Run lint + typecheck + tests + coverage + build +.PHONY: docs-lint +docs-lint: frontend-tooling ## Lint markdown files (tiny ruleset; avoids noisy churn) + $(NODE_WRAP) npx markdownlint-cli2@0.15.0 --config .markdownlint-cli2.yaml "**/*.md" + .PHONY: docs-link-check docs-link-check: ## Check for broken relative links in markdown docs python scripts/check_markdown_links.py + +.PHONY: docs-check +docs-check: docs-lint docs-link-check ## Run all docs quality gates diff --git a/backend/templates/AUTONOMY.md b/backend/templates/AUTONOMY.md index 0e22df5b..7cb418c8 100644 --- a/backend/templates/AUTONOMY.md +++ b/backend/templates/AUTONOMY.md @@ -31,4 +31,3 @@ This file defines how you decide when to act vs when to ask. ## Collaboration defaults - If you are idle/unassigned: pick 1 in-progress/review task owned by someone else and leave a concrete, helpful comment (context gaps, quality risks, validation ideas, edge cases, handoff clarity). - If you notice duplicate work: flag it and propose a merge/split so there is one clear DRI per deliverable. - diff --git a/backend/templates/SELF.md b/backend/templates/SELF.md index 1823bf61..9273927e 100644 --- a/backend/templates/SELF.md +++ b/backend/templates/SELF.md @@ -66,4 +66,3 @@ Notes: | Date | Change | |------|--------| | | | - diff --git a/docs/03-development.md b/docs/03-development.md new file mode 100644 index 00000000..4949c0c3 --- /dev/null +++ b/docs/03-development.md @@ -0,0 +1,3 @@ +# Development workflow + +Placeholder: see root `README.md` for current setup steps. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..80a9fbe9 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,18 @@ +# Mission Control docs + +This folder is the starting point for Mission Control documentation. + +## Sections + +- [Development workflow](./03-development.md) +- [Testing guide](./testing/README.md) +- [Coverage policy](./coverage-policy.md) +- [Deployment](./deployment/README.md) +- [Production notes](./production/README.md) +- [Troubleshooting](./troubleshooting/README.md) +- [Gateway WebSocket protocol](./openclaw_gateway_ws.md) + +## Status + +These pages are minimal placeholders so repo-relative links stay healthy. The actual docs +information architecture will be defined in the Docs overhaul tasks. diff --git a/docs/coverage-policy.md b/docs/coverage-policy.md new file mode 100644 index 00000000..4476e2a8 --- /dev/null +++ b/docs/coverage-policy.md @@ -0,0 +1,3 @@ +# Coverage policy + +Placeholder: coverage policy is currently documented in the root `Makefile` (`backend-coverage`). diff --git a/docs/deployment/README.md b/docs/deployment/README.md new file mode 100644 index 00000000..cb39e267 --- /dev/null +++ b/docs/deployment/README.md @@ -0,0 +1,3 @@ +# Deployment guide + +Placeholder. diff --git a/docs/openclaw_gateway_ws.md b/docs/openclaw_gateway_ws.md new file mode 100644 index 00000000..5fc7b84e --- /dev/null +++ b/docs/openclaw_gateway_ws.md @@ -0,0 +1,3 @@ +# Gateway WebSocket protocol + +Placeholder. diff --git a/docs/production/README.md b/docs/production/README.md new file mode 100644 index 00000000..e461bfde --- /dev/null +++ b/docs/production/README.md @@ -0,0 +1,3 @@ +# Production notes + +Placeholder. diff --git a/docs/testing/README.md b/docs/testing/README.md new file mode 100644 index 00000000..80dcee45 --- /dev/null +++ b/docs/testing/README.md @@ -0,0 +1,3 @@ +# Testing guide + +Placeholder: see root `README.md` and `CONTRIBUTING.md` for current commands. diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md new file mode 100644 index 00000000..1b897489 --- /dev/null +++ b/docs/troubleshooting/README.md @@ -0,0 +1,3 @@ +# Troubleshooting + +Placeholder. diff --git a/scripts/check_markdown_links.py b/scripts/check_markdown_links.py index e32c7f1c..9123cd79 100755 --- a/scripts/check_markdown_links.py +++ b/scripts/check_markdown_links.py @@ -27,18 +27,27 @@ LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)") def iter_md_files(root: Path) -> list[Path]: """Return markdown files to check. - Policy (initial): check only `docs/**/*.md`. + Policy: + - Always check root contributor-facing markdown (`README.md`, `CONTRIBUTING.md`). + - If `docs/` exists, also check `docs/**/*.md`. Rationale: - - Root `README.md` / `CONTRIBUTING.md` may temporarily contain legacy links - during docs re-org. Once docs + README are stabilized, we can expand this - to include root markdown files. + - We want fast feedback on broken *relative* links in the most important entrypoints. + - We intentionally do **not** crawl external URLs. """ + files: list[Path] = [] + + for p in (root / "README.md", root / "CONTRIBUTING.md"): + if p.exists(): + files.append(p) + docs = root / "docs" - if not docs.exists(): - return [] - return sorted(docs.rglob("*.md")) + if docs.exists(): + files.extend(sorted(docs.rglob("*.md"))) + + # de-dupe + stable order + return sorted({p.resolve() for p in files}) def normalize_target(raw: str) -> str | None: