Adopt apache/airflow-steward framework (pr-management skills via snapshot)#66677
Merged
Conversation
potiuk
requested review from
amoghrajesh,
ashb,
choo121600,
jason810496,
jscheffl,
kaxil and
shahar1
as code owners
3 tasks
potiuk
added a commit
to apache/magpie
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.
potiuk
force-pushed
the
adopt-airflow-steward
branch
from
ae05284 to
0757ed0
Compare
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.
The framework's bootstrap version that landed in the previous adoption commit didn't include Golden Rule 8 (always-on `setup-*` and `list-steward-*` families are wired unconditionally). Re-running `/setup-steward upgrade` followed by `/setup-steward` refreshed the snapshot to apache/magpie@54a2ce4 and surfaced the gap. Changes in this commit: - Refresh committed `.github/skills/setup-steward/` from the snapshot. Adds two new sub-actions the framework grew since the original adoption: `unadopt.md` and `worktree-init.md`. Re-applies the SPDX one-liner header the static-check fix from 8b59967 requires (the framework ships without it; the airflow static checks need it). - Extend `.gitignore` to cover the now-symlinked always-on families: `setup-override-upstream`, `list-steward-*`. The `setup-isolated-setup-*` patterns were already in place. Symlinks and the post-checkout hook the framework now installs are gitignored by design — they don't appear in this diff but are created on-disk by `/setup-steward` and reproduced on every fresh clone by re-running the same command per the contributor README section.
potiuk
force-pushed
the
adopt-airflow-steward
branch
from
0757ed0 to
ec22cfa
Compare
choo121600
approved these changes
May 18, 2026
Contributor
Backport failed to create: v3-2-test. View the failure log Run detailsNote: As of Merging PRs targeted for Airflow 3.X In matter of doubt please ask in #release-management Slack channel.
You can attempt to backport this manually by running: cherry_picker a255eeb v3-2-testThis should apply the commit to the v3-2-test branch and leave the commit in conflict state marking After you have resolved the conflicts, you can continue the backport process by running: cherry_picker --continueIf you don't have cherry-picker installed, see the installation guide. |
choo121600
reviewed
May 18, 2026
1 task
potiuk
added a commit
that referenced
this pull request
May 24, 2026
Backports the framework adoption from main (#66677 + #67149) so that v3-2-test gets the same agent-driven PR-management skills that main already uses, and so that future agentic fixes that ship as overrides under \`.apache-steward-overrides/\` cherry-pick cleanly to v3-2-test instead of hitting structural conflicts against the old self-hosted \`pr-triage\` skill. What changes: - Remove the self-hosted \`pr-triage\` skill at \`.github/skills/pr-triage/\` (and its symlink \`.claude/skills/pr-triage\`). Its functionality moves into the apache-steward framework as \`pr-management-triage\`, fetched on demand via the snapshot mechanism. - Wire up the apache-steward adoption: committed \`setup-steward\` bootstrap at \`.github/skills/setup-steward/\` (with a sibling \`.claude/skills/setup-steward\` symlink), \`.apache-steward.lock\` pinned to framework \`main\`, and the \`.apache-steward-overrides/\` directory with the three pr-management-triage config files (\`pr-management-config.md\`, \`pr-management-triage-ci-check-map.md\`, \`pr-management-triage-comment-templates.md\`) plus README and user.md. - Refresh the \`setup-steward\` bootstrap to the latest framework main (apache/magpie#247 — Pattern D single-directory-symlink layout) so adopters of the new framework benefit from the consolidated install flow. - Rewrite \`contributing-docs/25_maintainer_pr_triage.md\` to point at the framework skill URLs (\`apache/airflow-steward/.../pr-management-*\`) rather than the now-removed local skill paths. - Add the apache-steward section to \`AGENTS.md\` and the "Agent-assisted contribution" section to \`README.md\`. - Update \`.gitignore\` to allow-list \`setup-steward\` and to exclude the symlink families (\`security-*\`, \`pr-management-*\`, \`issue-*\`, \`setup-isolated-setup-*\`, \`setup-override-upstream\`, \`setup-shared-config-sync\`, \`list-steward-*\`) under both \`.claude/skills/\` and \`.github/skills/\`. - Update \`.pre-commit-config.yaml\` to skip \`.apache-steward-overrides/\` and \`.github/skills/setup-steward/\` in codespell and markdownlint (the framework prose uses hyphenated forms codespell flags as misspellings, and the snapshot-internal links break markdownlint). What does not change: - \`maintainer-review\` and \`pr-stats\` skills were never backported to v3-2-test, so there's nothing to remove for them — they will simply show up as \`pr-management-code-review\` and \`pr-management-stats\` after a fresh \`/setup-steward\`. - The \`lychee\` prek hook does not exist on v3-2-test, so its exclude hunk from main's adoption commit is N/A here. After this lands, contributors run \`/setup-steward\` in their agent harness to populate the gitignored \`.apache-steward/\` snapshot and make every \`pr-management-*\` skill invocable. See the README section "Agent-assisted contribution (apache-steward)" for the setup flow.
vatsrahul1001
pushed a commit
that referenced
this pull request
May 25, 2026
Backports the framework adoption from main (#66677 + #67149) so that v3-2-test gets the same agent-driven PR-management skills that main already uses, and so that future agentic fixes that ship as overrides under \`.apache-steward-overrides/\` cherry-pick cleanly to v3-2-test instead of hitting structural conflicts against the old self-hosted \`pr-triage\` skill. What changes: - Remove the self-hosted \`pr-triage\` skill at \`.github/skills/pr-triage/\` (and its symlink \`.claude/skills/pr-triage\`). Its functionality moves into the apache-steward framework as \`pr-management-triage\`, fetched on demand via the snapshot mechanism. - Wire up the apache-steward adoption: committed \`setup-steward\` bootstrap at \`.github/skills/setup-steward/\` (with a sibling \`.claude/skills/setup-steward\` symlink), \`.apache-steward.lock\` pinned to framework \`main\`, and the \`.apache-steward-overrides/\` directory with the three pr-management-triage config files (\`pr-management-config.md\`, \`pr-management-triage-ci-check-map.md\`, \`pr-management-triage-comment-templates.md\`) plus README and user.md. - Refresh the \`setup-steward\` bootstrap to the latest framework main (apache/magpie#247 — Pattern D single-directory-symlink layout) so adopters of the new framework benefit from the consolidated install flow. - Rewrite \`contributing-docs/25_maintainer_pr_triage.md\` to point at the framework skill URLs (\`apache/airflow-steward/.../pr-management-*\`) rather than the now-removed local skill paths. - Add the apache-steward section to \`AGENTS.md\` and the "Agent-assisted contribution" section to \`README.md\`. - Update \`.gitignore\` to allow-list \`setup-steward\` and to exclude the symlink families (\`security-*\`, \`pr-management-*\`, \`issue-*\`, \`setup-isolated-setup-*\`, \`setup-override-upstream\`, \`setup-shared-config-sync\`, \`list-steward-*\`) under both \`.claude/skills/\` and \`.github/skills/\`. - Update \`.pre-commit-config.yaml\` to skip \`.apache-steward-overrides/\` and \`.github/skills/setup-steward/\` in codespell and markdownlint (the framework prose uses hyphenated forms codespell flags as misspellings, and the snapshot-internal links break markdownlint). What does not change: - \`maintainer-review\` and \`pr-stats\` skills were never backported to v3-2-test, so there's nothing to remove for them — they will simply show up as \`pr-management-code-review\` and \`pr-management-stats\` after a fresh \`/setup-steward\`. - The \`lychee\` prek hook does not exist on v3-2-test, so its exclude hunk from main's adoption commit is N/A here. After this lands, contributors run \`/setup-steward\` in their agent harness to populate the gitignored \`.apache-steward/\` snapshot and make every \`pr-management-*\` skill invocable. See the README section "Agent-assisted contribution (apache-steward)" for the setup flow.
vatsrahul1001
pushed a commit
that referenced
this pull request
May 25, 2026
Backports the framework adoption from main (#66677 + #67149) so that v3-2-test gets the same agent-driven PR-management skills that main already uses, and so that future agentic fixes that ship as overrides under \`.apache-steward-overrides/\` cherry-pick cleanly to v3-2-test instead of hitting structural conflicts against the old self-hosted \`pr-triage\` skill. What changes: - Remove the self-hosted \`pr-triage\` skill at \`.github/skills/pr-triage/\` (and its symlink \`.claude/skills/pr-triage\`). Its functionality moves into the apache-steward framework as \`pr-management-triage\`, fetched on demand via the snapshot mechanism. - Wire up the apache-steward adoption: committed \`setup-steward\` bootstrap at \`.github/skills/setup-steward/\` (with a sibling \`.claude/skills/setup-steward\` symlink), \`.apache-steward.lock\` pinned to framework \`main\`, and the \`.apache-steward-overrides/\` directory with the three pr-management-triage config files (\`pr-management-config.md\`, \`pr-management-triage-ci-check-map.md\`, \`pr-management-triage-comment-templates.md\`) plus README and user.md. - Refresh the \`setup-steward\` bootstrap to the latest framework main (apache/magpie#247 — Pattern D single-directory-symlink layout) so adopters of the new framework benefit from the consolidated install flow. - Rewrite \`contributing-docs/25_maintainer_pr_triage.md\` to point at the framework skill URLs (\`apache/airflow-steward/.../pr-management-*\`) rather than the now-removed local skill paths. - Add the apache-steward section to \`AGENTS.md\` and the "Agent-assisted contribution" section to \`README.md\`. - Update \`.gitignore\` to allow-list \`setup-steward\` and to exclude the symlink families (\`security-*\`, \`pr-management-*\`, \`issue-*\`, \`setup-isolated-setup-*\`, \`setup-override-upstream\`, \`setup-shared-config-sync\`, \`list-steward-*\`) under both \`.claude/skills/\` and \`.github/skills/\`. - Update \`.pre-commit-config.yaml\` to skip \`.apache-steward-overrides/\` and \`.github/skills/setup-steward/\` in codespell and markdownlint (the framework prose uses hyphenated forms codespell flags as misspellings, and the snapshot-internal links break markdownlint). What does not change: - \`maintainer-review\` and \`pr-stats\` skills were never backported to v3-2-test, so there's nothing to remove for them — they will simply show up as \`pr-management-code-review\` and \`pr-management-stats\` after a fresh \`/setup-steward\`. - The \`lychee\` prek hook does not exist on v3-2-test, so its exclude hunk from main's adoption commit is N/A here. After this lands, contributors run \`/setup-steward\` in their agent harness to populate the gitignored \`.apache-steward/\` snapshot and make every \`pr-management-*\` skill invocable. See the README section "Agent-assisted contribution (apache-steward)" for the setup flow.
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.
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