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
Copy link
Copy Markdown
Member

@potiuk potiuk commented May 3, 2026

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/airflow-steward#38.

Generated-by: Claude Code (Claude Opus 4.7)
@boring-cyborg boring-cyborg Bot added area:dev-tools backport-to-v3-2-test Mark PR with this label to backport to v3-2-test branch labels May 3, 2026
@Srabasti
Copy link
Copy Markdown
Contributor

Srabasti commented May 5, 2026

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
Copy link
Copy Markdown
Member Author

potiuk commented May 6, 2026

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

Labels

area:dev-tools backport-to-v3-2-test Mark PR with this label to backport to v3-2-test branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants