Adopt apache/airflow-steward framework (pr-management skills via snapshot)#66677
Open
potiuk wants to merge 5 commits into
Open
Adopt apache/airflow-steward framework (pr-management skills via snapshot)#66677potiuk wants to merge 5 commits into
potiuk wants to merge 5 commits into
Conversation
potiuk
requested review from
amoghrajesh,
ashb,
choo121600,
jason810496,
jscheffl,
kaxil and
shahar1
as code owners
boring-cyborg
Bot
added
area:dev-tools
backport-to-v3-2-test
3 tasks
potiuk
added a commit
to apache/airflow-steward
that referenced
this pull request
May 11, 2026
Step 11 (project doc updates) previously said only "add a brief paragraph to README.md or CONTRIBUTING.md noting three things", which left every adopter to reinvent the wording. Replace it with: - a copy-pasteable `## Agent-assisted contribution (apache-steward)` section for README.md, with substitution guidance for the adopter's skill-family choices and the flat-vs-double-symlinked path convention; - an explicit note about PyPI sync markers (avoid leaking the adoption blurb into the published PyPI description on projects that round-trip README.md to PyPI); - a separate AGENTS.md template that agent harnesses see first, with a cross-reference back to the README section so the agent lands on the human-readable summary rather than duplicating the prose; - a "do not create AGENTS.md if it does not already exist" guardrail (empty file is more noise than signal); - a doctoc/TOC-hook note so adopters know to expect a second commit touching the auto-updated TOC block; - CONTRIBUTING.md as a documented fallback when README.md is absent or strictly off-limits. Update verify.md check 9 in parallel: grep for both `apache-steward` and `/setup-steward` tokens in README.md (and the cross-reference link in AGENTS.md if the file exists) rather than the previous "mentions the framework somewhere" hand-wave. Stay at ⚠ severity — these are nice-to-have, not blocking. Motivated by the apache/airflow adoption PR (apache/airflow#66677) which added both files by hand; the templates here capture what landed there so the next adopter gets it from the skill rather than from the airflow PR diff.
These three skills were moved into the apache/airflow-steward framework as pr-management-triage, pr-management-code-review, and pr-management-stats respectively. They will be provided by the framework via the adoption flow that follows this commit.
Wire up the apache-steward framework using the install recipe for
git-branch method (Method 3) pinned at branch `main`. The framework
provides the pr-management-* skills (triage, code-review, stats,
mentor) that replace the three local skills removed in the previous
commit.
Committed:
- `.github/skills/setup-steward/` — the only framework artefact that
lives in the adopter repo (per the framework's adoption contract);
every other framework skill is a gitignored symlink into the
gitignored snapshot at `.apache-steward/`.
- `.claude/skills/setup-steward` — symlink into the above (matches
airflow's existing double-symlinked skills convention).
- `.apache-steward.lock` — project pin (git-branch / main). Future
developers cloning this repo run `/setup-steward` to fetch the
snapshot per this pin.
- `.apache-steward-overrides/{README,user}.md` — scaffold for
adopter-specific workflow modifications and per-developer
preferences.
- AGENTS.md — section describing the framework adoption.
Gitignored (build artefacts / per-machine state):
- `.apache-steward/` — the snapshot directory itself.
- `.apache-steward.local.lock` — per-machine record of what was
fetched (compared to the committed lock to detect drift).
- `.claude/skills/{security-*,pr-management-*,setup-isolated-setup-*,setup-shared-config-sync}`
and the matching `.github/skills/*` paths — symlinks created by
`/setup-steward adopt`.
Adopter conventions followed:
- Existing `.claude/skills/*` blanket-ignore preserved; only
`aip-user-stories` (this repo's local skill) and `setup-steward`
(framework entry-point) are explicitly allow-listed.
Add a contributor-facing "Agent-assisted contribution (apache-steward)" section to README.md that: - explains the snapshot mechanism (gitignored `.apache-steward/`, committed `.apache-steward.lock`, committed `setup-steward` skill); - tells fresh-clone contributors to run `/setup-steward` (or follow `.claude/skills/setup-steward/`) to populate the framework before any `pr-management-*` skill is invocable; - points at `.apache-steward-overrides/` for adopter-specific workflow modifications and at `apache/airflow-steward` for framework changes. The section is placed outside the PyPI sync markers so it does not leak into PyPI. `doctoc` auto-updated the TOC. Cross-reference the new section from the matching block in `AGENTS.md` so agents land on the contributor-facing summary first.
The pr-management-triage / pr-management-stats / pr-management-code-review skills resolve project-specific values from `<project-config>/`. Copy the three pr-management-* files from the framework's projects/_template/ directory into `.apache-steward-overrides/` so the skills have: - committers team handle (`apache/airflow-committers`) - area label prefix (`area:`) - project-specific labels (`ready for maintainer review`, `closed because of multiple quality violations`, `suspicious changes detected`) - grace windows for stale sweeps - comment templates (with airflow doc URLs and AI-attribution footer wording for airflow's two-stage triage process) - CI-check-name pattern → category mapping The framework's templates were authored from Airflow's own values, so the copies need no further customisation. Future framework refactors that change the template surface will require manual reconciliation in these adopter copies.
- Insert Apache license headers in .apache-steward-overrides/*.md (5 files) via the insert-license hook auto-fix. - Normalize SPDX one-liner header indent in .github/skills/setup-steward/*.md (6 files) to match the scripts/ci/license-templates/SHORT_LICENSE.md template. - Exclude .apache-steward-overrides/ and .github/skills/setup-steward/ from lychee and markdownlint — the framework files internally reference paths under the gitignored .apache-steward/ snapshot, which doesn't exist in a fresh CI checkout. - Exclude .github/skills/setup-steward/ from codespell — the framework's prose uses hyphenated forms (pre-empt, re-use, Pre-select) that codespell flags as misspellings but shouldn't be modified locally (they're snapshot files; fixing should happen upstream in apache/airflow-steward). - Update contributing-docs/25_maintainer_pr_triage.md links from old skill names (pr-triage, pr-stats) to framework URLs (pr-management-triage, pr-management-stats) since the local skills were removed by this PR.
potiuk
force-pushed
the
adopt-airflow-steward
branch
from
ae05284 to
0757ed0
Compare
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
1 participant
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.
Adopts the
apache/airflow-stewardframework via its snapshot-based adoption mechanism (Method 3 — git-branch pinned atmain, the current pre-release path). The framework provides four maintainer-facing PR-management skills (pr-management-triage,pr-management-code-review,pr-management-stats,pr-management-mentor) that supersede the three local skills this PR removes.What's in each commit
Remove
pr-triage,maintainer-review,pr-statsskills. These moved into the framework (renamed topr-management-*); the framework provides them via gitignored symlinks the/setup-stewardflow wires up.Adopt apache/airflow-steward via snapshot mechanism. Wires up the framework per
docs/setup/install-recipes.md:setup-stewardskill (the only framework artefact an adopter commits), the project pin (.apache-steward.lock), and the.apache-steward-overrides/scaffold (README.md+user.md).AGENTS.md.!.claude/skills/pr-stats/pr-triage/maintainer-reviewallowlist entries and adds!.claude/skills/setup-steward.Document apache-steward adoption in README contributor section. Adds an "Agent-assisted contribution (apache-steward)" section to
README.md(outside the PyPI sync markers) that tells fresh-clone contributors to run/setup-steward. Cross-references fromAGENTS.md.doctocauto-updated the TOC.Notes for reviewers
aip-user-storiesskill is preserved (not provided by the framework).pr-managementskill family is installed; thesecurityfamily can be added later via/setup-steward overrideif/when needed.Was generative AI tooling used to co-author this PR?
Generated-by: Claude Opus 4.7 (1M context) following the guidelines