Skip to content

feat: adopt apache/airflow-steward via snapshot+overrides mechanism#66319

Closed
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:feat/adopt-apache-steward-snapshot-mechanism
Closed

feat: adopt apache/airflow-steward via snapshot+overrides mechanism#66319
potiuk wants to merge 1 commit into
apache:mainfrom
potiuk:feat/adopt-apache-steward-snapshot-mechanism

Conversation

@potiuk

@potiuk potiuk commented May 3, 2026

Copy link
Copy Markdown
Member

Summary

Apache Airflow becomes an adopter of the apache/airflow-steward framework using the snapshot + agentic-overrides adoption mechanism. The previous in-repo PR-skill copies (pr-triage, pr-stats, maintainer-review) are replaced by the framework's renamed pr-management-* family delivered through the framework.

This supersedes the closed #66283, which used a git-submodule design that we ultimately rejected.

How adoption works

The framework lives in a gitignored .apache-steward/ directory in this repo, refreshed by the framework's own setup-steward skill. The only framework artefact this PR commits is that bootstrap skill itself — at .github/skills/setup-steward/ (matching airflow's existing .claude/skills/<n>.github/skills/<n>/ double-symlink convention).

On a fresh clone, the framework's other skills are not yet on disk. To populate them:

# tell your agent: "adopt apache-steward in this repo"
# OR invoke /setup-steward directly

The setup-steward skill then:

  • Downloads the framework into .apache-steward/ (gitignored, refreshed via /setup-steward upgrade).
  • Creates gitignored symlinks under .github/skills/<framework-skill>/.apache-steward/.claude/skills/<framework-skill>/.
  • Wires up matching gitignored symlinks under .claude/skills/ so Claude Code picks them up.
  • Recreates everything if a worktree is checked out off this repo (post-checkout hook).

What lands committed

File Purpose
.github/skills/setup-steward/ (+ .claude/skills/setup-steward symlink) The bootstrap skill — the only framework artefact this repo commits.
.gitignore Gitignore .apache-steward/, the runtime framework symlinks; remove old in-repo skill exemptions; add setup-steward exemption.
.apache-steward.lock Pins the snapshot to commit 84852ca1a0…. Updated by /setup-steward upgrade.
.apache-steward-overrides/README.md Override-directory scaffold. Adopter-specific deviations live here.
.markdownlintignore Skip the framework's skill files (they follow the framework's markdownlint conventions; already linted upstream).
CLAUDE.md (= AGENTS.md) Short adoption note explaining the bootstrap flow.
contributing-docs/25_maintainer_pr_triage.md Top-of-doc notice that skills now live in the framework + path updates pr-triagepr-management-triage etc.

What got deleted

  • .github/skills/pr-triage/, .github/skills/pr-stats/, .github/skills/maintainer-review/ — replaced by pr-management-{triage,stats,code-review} from the framework.
  • The corresponding .claude/skills/ symlinks.

What stays untouched

  • .github/skills/aip-user-stories/, .github/skills/airflow-translations/, .github/skills/prepare-providers-documentation/ — airflow-only skills that don't migrate to the framework.
  • The .claude/skills/aip-user-stories symlink.

Test plan

  • prek run passes locally (markdownlint, codespell, license-header, …)
  • setup-steward skill registers in Claude Code's available-skills (live discovery picks it up)
  • .gitignore correctly ignores .apache-steward/ and the gitignored symlinks
  • Reviewer runs /setup-steward against a fresh clone of this branch to verify the end-to-end adoption flow
  • Reviewer eyeballs the deletion of pr-triage/pr-stats/maintainer-review for any in-repo references not covered by the contributing-docs path update
  • CI passes

Out of scope

  • Deeper rewrite of contributing-docs/25_maintainer_pr_triage.md to reflect the framework's pr-management-* skill structure (steps, decision tables, etc.). This PR does the path renames + top-of-doc notice; a follow-up can do the substantive update once maintainers have run /setup-steward and read the new framework's skill files.
  • Re-adopting the security-issue handling family (those skills run from the private apache/airflow-s security tracker, not from this public upstream).

🤖 Generated with Claude Code

Apache Airflow becomes an adopter of the
[apache/airflow-steward](https://github.com/apache/airflow-steward)
framework, which ships maintainer-facing skills as a project-
agnostic library. The previous in-repo copies of the
PR-triage / PR-stats / maintainer-review skills are replaced
by the framework's renamed `pr-management-*` family delivered
through the framework's snapshot + agentic-overrides mechanism.

What lands committed in this PR

- .github/skills/setup-steward/ + .claude/skills/setup-steward
  symlink (matching airflow's existing
  .claude/skills/<n> -> .github/skills/<n>/ double-symlink
  convention) — the framework's bootstrap skill, copied from
  apache/airflow-steward main. This is the only framework
  artefact airflow commits.
- .gitignore — gitignore .apache-steward/ (the framework
  snapshot — a build artefact, refreshed by /setup-steward),
  remove the explicit pr-triage/pr-stats/maintainer-review
  exemptions (they're gone), add a setup-steward exemption,
  and gitignore the framework's runtime symlinks under
  .github/skills/.
- .apache-steward.lock — pins the snapshot to a specific
  framework commit. Updated by /setup-steward upgrade.
- .apache-steward-overrides/README.md — the override-directory
  scaffold. Adopter-specific deviations from framework
  workflows live here, committed.
- .markdownlintignore — skip the framework's skill markdown
  files (they follow the framework's own markdownlint
  convention; already linted upstream).
- CLAUDE.md / AGENTS.md — short adoption note explaining the
  bootstrap flow ("tell your agent: adopt apache-steward in
  this repo").
- contributing-docs/25_maintainer_pr_triage.md — top-of-doc
  notice that skills now live in the framework, plus path
  updates from pr-triage/pr-stats/maintainer-review to the
  pr-management-* names.

What got deleted

- .github/skills/pr-triage/, .github/skills/pr-stats/,
  .github/skills/maintainer-review/ (the in-repo copies — now
  delivered via the framework as
  pr-management-{triage,stats,code-review}).
- The corresponding .claude/skills/ symlinks.

What stays untouched

- .github/skills/aip-user-stories/, .github/skills/airflow-translations/,
  .github/skills/prepare-providers-documentation/ (airflow-only
  skills that don't migrate to the framework).
- The corresponding .claude/skills/ symlink for aip-user-stories.

Bootstrap flow on a fresh clone

  $ git clone <fork>
  $ cd airflow
  $ # tell your agent: "adopt apache-steward in this repo"
  $ # OR invoke /setup-steward directly

  /setup-steward downloads the framework into .apache-steward/
  (gitignored), creates gitignored symlinks under
  .github/skills/<n> -> .apache-steward/.claude/skills/<n>/ for
  every framework skill the project uses, and refreshes both on
  /setup-steward upgrade.

Replaces the closed apache#66283 (the original submodule-
based adoption attempt) per the design pivot documented in
apache/magpie#38.

Generated-by: Claude Code (Claude Opus 4.7)
@Srabasti

Srabasti commented May 5, 2026

Copy link
Copy Markdown
Contributor

Hello @potiuk
Looks like the new file ".markdownlintignore" is added, however ".rat-excludes" is not updated to include it and tell RAT to ignore it.
Shall we update it instead of adding an Apache License header to it?

@potiuk

potiuk commented May 6, 2026

Copy link
Copy Markdown
Member Author

No no... I will have to redo it

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants