docs: tighten Airflow references to placeholders across framework files#1
Merged
Conversation
Mechanical sanitization pass replacing literal Airflow URLs and ASF-domain strings with placeholders, leaving illustrative "(example: …)" parentheticals intact: - airflow.apache.org/docs/.../security_model.html → <security-model-url> - https://airflow.apache.org/ → <project-website>/ - security.airflow.apache.org → <security-list-domain> - domain: "airflow.apache.org" (in ponymail/gmail code samples) → <project-domain> - `Apache Airflow:` literal title prefix → described as <vendor>: <product>: with Airflow as illustrative example Affects 13 files (5 skills + 6 tool docs + README + CONTRIBUTING). Remaining "Apache Airflow" references are in placeholder-convention tables, "(example: …)" parentheticals, and the vulnogram SKILL.md documenting the airflow-specific reference implementation — all within the "Airflow as example in comments" rule from .../airflow-steward repository conventions. Generated-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6 tasks
potiuk
referenced
this pull request
in andreahlert/magpie
May 1, 2026
…, lychee) Adds a minimal doc-validation layer to pre-commit + a lychee link-check workflow. Catches the bug classes review currently has to find by eye: - markdownlint-cli2 with a tight config (MD051 broken anchors, MD053 dangling link refs); style rules off so the diff stays small - typos with project-term allowlist in .typos.toml (CNA, Vulnogram, ponymail, mis-, Nd, pre-empted) - tools/dev/check-placeholders.sh refuses hardcoded apache/airflow / Apache Airflow inside .claude/skills/ and tools/*.md (PR #1 already had to scrub these once) - lychee runs in a separate workflow on PR + daily cron; informational only today (continue-on-error: true) because the existing tree has 24 pre-existing broken refs to files that have not landed yet (config/, projects/airflow/, the issue-template YAML); flips to a hard gate once the baseline reaches zero Wiring this up surfaced five real broken anchors I fixed along the way: - AGENTS.md missing "the project's" prefix in #point-reporters-to-the-security-model-dont-re-explain-it - tools/ponymail/operations.md anchors #get-email and #get-thread pointed at headings that are actually "Get an email" / "Get a thread" - projects/_template/scope-labels.md and tools/github/issue-template.md carried headings with a literal "→" that GitHub URL-encodes into unresolvable slugs; renamed to "to" and re-ran doctoc Signed-off-by: André Ahlert <andre@aex.partners>
potiuk
added a commit
that referenced
this pull request
May 1, 2026
…, lychee) (#18) * ci: add doc-validation hooks (markdownlint, typos, placeholder linter, lychee) Adds a minimal doc-validation layer to pre-commit + a lychee link-check workflow. Catches the bug classes review currently has to find by eye: - markdownlint-cli2 with a tight config (MD051 broken anchors, MD053 dangling link refs); style rules off so the diff stays small - typos with project-term allowlist in .typos.toml (CNA, Vulnogram, ponymail, mis-, Nd, pre-empted) - tools/dev/check-placeholders.sh refuses hardcoded apache/airflow / Apache Airflow inside .claude/skills/ and tools/*.md (PR #1 already had to scrub these once) - lychee runs in a separate workflow on PR + daily cron; informational only today (continue-on-error: true) because the existing tree has 24 pre-existing broken refs to files that have not landed yet (config/, projects/airflow/, the issue-template YAML); flips to a hard gate once the baseline reaches zero Wiring this up surfaced five real broken anchors I fixed along the way: - AGENTS.md missing "the project's" prefix in #point-reporters-to-the-security-model-dont-re-explain-it - tools/ponymail/operations.md anchors #get-email and #get-thread pointed at headings that are actually "Get an email" / "Get a thread" - projects/_template/scope-labels.md and tools/github/issue-template.md carried headings with a literal "→" that GitHub URL-encodes into unresolvable slugs; renamed to "to" and re-ran doctoc Signed-off-by: André Ahlert <andre@aex.partners> * fix(ci): bump node language version + use ASF-allowlisted lychee-action SHA PR #18's first CI run failed three checks; this fixup commit addresses all three: - prek / markdownlint — markdownlint-cli2 v0.22.1 requires Node ≥ 20 (its string-width dep uses the regex `/v` flag), but `default_language_version.node` was pinned to 18.6.0. Bumped to 22.11.0 (current active LTS). - asf-allowlist-check — `lycheeverse/lychee-action@82202e5e…` (v2.6.1) is not on the ASF infrastructure-actions allowlist. Re-pinned to the allowlisted v2.8.0 SHA `8646ba30535128ac92d33dfc9133794bfdd9b411`. Comment in the workflow now explains the allowlist requirement so future bumps go through the same check. - zizmor (ref-version-mismatch) — the v2.6.1-comment + actual-SHA combination from the original pin was flagged because the SHA pointed to v2.4.1, not v2.6.1. The new v2.8.0 SHA correctly maps to its tag, so the warning disappears with the same change. prek + zizmor verified clean locally. Generated-by: Claude Code (Opus 4.7) --------- Signed-off-by: André Ahlert <andre@aex.partners> Co-authored-by: Jarek Potiuk <jarek@potiuk.com>
andreahlert
added
the
mode:platform
6 tasks
3 tasks
4 tasks
This was referenced May 26, 2026
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up sanitization pass on the framework, replacing literal Airflow URLs and ASF-domain strings with the framework's placeholder convention. Remaining "Apache Airflow" references are in legitimate
(example: …)parentheticals, placeholder-convention tables, and the vulnogram SKILL.md documenting the airflow-specific reference implementation — all within the "Airflow as example in comments" rule.What's substituted
airflow.apache.org/docs/.../security_model.html<security-model-url>https://airflow.apache.org/(project website)<project-website>/security.airflow.apache.org(security-list domain)<security-list-domain>domain: "airflow.apache.org"(in ponymail/gmail code)domain: "<project-domain>"`Apache Airflow:`(literal title prefix)`<vendor>: <product>:` (e.g. `Apache Airflow:`)Files touched
13 files: 5 skills (
allocate-cve,import-security-issue,import-security-issue-from-pr,invalidate-security-issue,sync-security-issue), 6 tool docs (tools/{ponymail,gmail,vulnogram}/*.md),README.md, andCONTRIBUTING.md.Test plan
Apache Airflow/airflow.apache.org/apache/airflow/airflow-s/airflow-smentions dropped from ~50 to ~36.(example: …)parentheticals or placeholder tables.tools/vulnogram/generate-cve-json/Python implementation to be project-agnostic (currently airflow-specific defaults; the SKILL.md still describes airflow defaults). Once refactored, the framework can ship the implementation, and the SKILL.md can drop the Airflow-specific examples.🤖 Generated with Claude Code