eSlider
e6e57843cb
CI & Release / Verify documentation (push) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify documentation (pull_request) Successful in 5s
CI & Release / Verify simulator (pull_request) Failing after 9s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
Enforce link resolution, glossary anchors, and readability rules on every push and PR; docs-only pushes to main still run docs-verify while skipping the simulator gate.
57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# CI documentation rules
|
|
|
|
Automated checks for markdown in this repository. Enforced on every **pull request** and on **push to `main`** (including docs-only pushes that skip the simulator gate).
|
|
|
|
Implementation: [`scripts/check_docs.py`](../../scripts/check_docs.py) reads [`scripts/docs_rules.yaml`](../../scripts/docs_rules.yaml).
|
|
|
|
Workflow: [`.github/workflows/release.yaml`](../../.github/workflows/release.yaml) job **`Verify documentation`**.
|
|
|
|
Tracked from [issue #1](https://git.produktor.io/eSlider/swarm-house/issues/1) and the [2026-07-10 audit](2026-07-10-audit.md).
|
|
|
|
## Gates
|
|
|
|
| Rule | Severity | What it checks |
|
|
| --- | --- | --- |
|
|
| Relative links | error | Every `[text](path)` and `[text](path#anchor)` to a local `.md` file resolves to an existing file |
|
|
| Fragment anchors | error | `#anchor` fragments match a `##` or `###` heading in the target file (GitHub-style slug) |
|
|
| Banned targets | error | Known-bad paths (e.g. deleted `03-storage-design.md`) are not linked |
|
|
| Glossary fragments | error | All `00-glossary.md#…` links use anchors that exist in the glossary |
|
|
| Section vs term links | warning | Links to glossary *section* headers (`#swarm--robotics`, …) are listed; prefer `###` term anchors where they exist |
|
|
| Bare cross-refs | error | Prose cross-references to numbered docs without a proper markdown link |
|
|
|
|
Warnings are printed in the job log but do not fail CI. Errors exit non-zero and block merge.
|
|
|
|
## PR workflow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
PR[Pull request] --> DV[docs-verify]
|
|
PR --> V[verify simulator]
|
|
V --> S[Trivy scan]
|
|
DV --> OK{All required green?}
|
|
V --> OK
|
|
S --> OK
|
|
OK -->|yes| Merge[Mergeable]
|
|
```
|
|
|
|
| Event | `docs-verify` | `verify` + `scan` |
|
|
| --- | --- | --- |
|
|
| PR → `main` | always | always |
|
|
| Push → `main` (code paths) | always | runs |
|
|
| Push → `main` (docs/README/AGENTS only) | always | skipped (`paths-ignore`) |
|
|
|
|
Docs-only changes therefore still get link and glossary validation on `main`; they do not trigger a semantic release.
|
|
|
|
## Local run
|
|
|
|
```bash
|
|
python scripts/check_docs.py
|
|
python scripts/check_docs.py --warnings-as-errors # treat section-link warnings as failures
|
|
```
|
|
|
|
## Changing rules
|
|
|
|
1. Edit `scripts/docs_rules.yaml` (paths, banned targets, preferred anchors).
|
|
2. Adjust `scripts/check_docs.py` only when adding a new rule *type*.
|
|
3. Add a row to the table above and mention it in the audit/improvement record if the change is significant.
|