Skip to content

ci: gate PRs on local links; stop publishing the ADRs - #165

Merged
lesnik512 merged 1 commit into
mainfrom
ci/offline-link-gate
Sep 6, 2026
Merged

ci: gate PRs on local links; stop publishing the ADRs#165
lesnik512 merged 1 commit into
mainfrom
ci/offline-link-gate

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

mkdocs build --strict validates links inside docs/ only. Root Markdown, .github/
and docs/agents/ are unchecked — AGENTS.md already says so. Nothing catches
a broken relative link in AGENTS.md, CONTEXT.md, or the README.

A relative link breaks because a diff broke it. Unlike an external URL it needs no network
and cannot flake, so it belongs on the PR that breaks it rather than in a scheduled job.

Design

One job in _checks.yml, so it runs wherever _checks.yml already runs. --offline blocks
all network requests and excludes external URLs rather than erroring on them, which is
what makes the gate deterministic and safe to block on. No exclusions, no token, no schedule.

The ADRs stop being published. not_in_nav existed for exactly one reason — build them
so --strict validates their outgoing links. The gate does that now, from disk, so /adr/
moves to exclude_docs.

Non-goals

  • No external link checking here. That runs weekly in modern-python/.github and stays
    there; sharing it across repos was considered and rejected (Offer the link checker to the other repos as a reusable workflow .github#64).

  • --include-fragments stays off — and this repo is the reason. Turning it on fails
    five links in docs/ as Cannot find fragment, and all five resolve correctly on the
    built site
    :

    Heading python-markdown slug (what MkDocs emits)
    Slow handlers — dedicated queue slow-handlers-dedicated-queue
    Drain & lifecycle drain-lifecycle
    vs. FastStream + `KafkaBroker` / `RabbitBroker` directly vs-faststream-kafkabroker-rabbitbroker-directly

    lychee computes GitHub-flavoured slugs, which leave a doubled hyphen where an em dash,
    & or backticks were. Verified by running markdown.extensions.toc.slugify directly.

Verification

  • lychee --offline on this tree: 241 total, 202 OK, 0 errors — the gate lands green.
  • just docs-build passes, and site/adr/ is confirmed absent from the build.
  • No Python changed, so the test suite is untouched by this diff and I have not run it.

Before merging

`mkdocs --strict` validates links inside docs/ only — root Markdown, .github/ and
docs/agents/ are unchecked, which AGENTS.md already notes. A relative link breaks
because a diff broke it, so the check belongs on the PR that breaks it: --offline
blocks network requests and excludes external URLs rather than erroring on them, so
the gate is deterministic and cannot flake.

That also retires the reason the ADRs were built at all. not_in_nav existed so
--strict would validate their outgoing links; the gate now validates them from disk,
so they move to exclude_docs and stop being served.

Verified: lychee --offline reports 202 OK, 0 errors; `just docs-build` passes and
site/adr/ is gone.

--include-fragments is deliberately off, and this repo is why. With it on, five links
in docs/ fail as "Cannot find fragment" — every one resolves correctly on the built
site. lychee computes GitHub-flavoured heading slugs; MkDocs uses python-markdown's,
which collapses `Slow handlers — dedicated queue` and `Drain & lifecycle` to a single
hyphen where GitHub leaves two. Confirmed against markdown.extensions.toc.slugify.

Part of modern-python/.github#66.
@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown

Benchmark gate

✅ gate passed

scenario msg/s delete/msg WALrec/msg WALB/msg fpi upd del dead_tup
consumer/w1/b10 1065 1.000 6.79 917 242 5000 5000 10000
consumer/w1/b100 1061 1.000 6.82 920 243 5000 5000 10000
consumer/w2/b10 1201 1.000 6.81 970 242 5000 5000 10000
consumer/w2/b100 1384 1.000 6.73 956 243 5000 5000 10000
consumer/w4/b10 1119 1.000 6.82 996 264 5000 5000 10000
consumer/w4/b100 1540 1.000 6.87 1039 245 5000 5000 10000
consumer/w1/b100/tfbs100 5860 0.010 6.07 1116 243 5000 5000 10000
producer/w1/b100 2393 0.000 3.04 584 0 0 0 0

Gated (fails the build): delete_calls + tuple counters (upd/del/ins) + the producer's insert_calls, exact; select_calls within +2; wal_records within a 10% band. msg/s, WAL bytes and total calls are informational (timing/FPI noise).

@lesnik512
lesnik512 merged commit 41c4dcd into main Sep 6, 2026
9 checks passed
@lesnik512
lesnik512 deleted the ci/offline-link-gate branch September 6, 2026 15:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant