This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 895477f docs(agents): require lychee local-run on every PR — added to
Before submitting (#411)
895477f is described below
commit 895477fb06586ca599efe6a3fbae87dd77787bf7
Author: Jarek Potiuk <[email protected]>
AuthorDate: Sun May 31 12:59:04 2026 +0200
docs(agents): require lychee local-run on every PR — added to Before
submitting (#411)
* docs(agents): require lychee local-run on every PR — added to Before
submitting
Caught a Fragment-not-found regression in PR #410 only when CI
flagged it. The check is cheap to run locally (offline file + fragment
lookups; only the external-URL subset hits the network) and catching
it before the push avoids a round-trip.
Add to the Before-submitting checklist:
- the canonical invocation (lychee --config .lychee.toml .)
- guidance on the most common breakage class (Fragment not found)
which is what bites on doc refactors that move sections between
files or rename headings
- a one-liner for v0.24+ local lychee installations (since .lychee.toml
pins the v0.23 schema)
The rule is enforce-via-CI either way (the lychee workflow blocks the
merge on any failure); this is just a documentation reminder so
agents add it to their pre-push routine and avoid the round-trip.
* fix(AGENTS.md): link to link-check.yml, not the made-up doc-validation.yml
The "Before submitting" lychee guidance pointed at
`.github/workflows/doc-validation.yml`, which does not exist —
this repo's link-check workflow is `link-check.yml`. Caught by
running lychee on the same file the PR added (which is what the
new rule itself prescribes).
---
AGENTS.md | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 7eb849f..e5de3a5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1681,6 +1681,32 @@ that does not change what the model is asked to produce —
- Re-read the diff and check that every change is intentional.
- Check that any renamed headings have matching TOC updates.
+- **Run lychee against every changed `.md` / `.rst` / `.md.j2` file.**
+ CI runs the same check on every PR and a single broken link blocks
+ the merge; catching it locally avoids a round-trip. The canonical
+ recipe — same as
+ [`.github/workflows/link-check.yml`](.github/workflows/link-check.yml)
+ invokes:
+
+ ```bash
+ lychee --config .lychee.toml .
+ ```
+
+ Run on the whole repo (cheap — most checks are offline file +
+ fragment lookups; only the external-URL subset hits the network).
+ Pay attention to **`Fragment not found in document`** errors —
+ those are anchor-style links (`other.md#section`) whose target
+ heading no longer exists. They are the most common breakage after
+ any refactor that moved a section between files or renamed a
+ heading. Re-write the link to point at the new location; do not
+ silence it with an ignore-pattern.
+
+ If your local lychee is v0.24+ (the example config in
+ `.lychee.toml` pins the v0.23 schema), replace
+ `include_fragments = true` with `include_fragments = "anchor-only"`
+ before running, or invoke directly:
+ `lychee --include-fragments=anchor-only --no-progress <paths>`.
+
- Verify that links to the project's Security Model use an anchor that
exists on the current stable version (adopting project's anchors:
[`<project-config>/security-model.md`](<project-config>/security-model.md)).
