This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 9774cc9 docs: extend Adopting the framework section for PR-skill
adopter contract (#34)
9774cc9 is described below
commit 9774cc927b1d4cb02278d5e1a33ba660cb2d5ec2
Author: Jarek Potiuk <[email protected]>
AuthorDate: Sat May 2 18:20:44 2026 +0200
docs: extend Adopting the framework section for PR-skill adopter contract
(#34)
Two doc surfaces updated to surface the four PR-skill scaffold
files added in #33:
- **Top-level README `## Adopting the framework`** — restructured
into four subsections:
- `Bootstrapping a new adopter` — three concrete steps (submodule
add, copy `_template/`, symlink `.claude/skills/`) with the
actual commands;
- `Per-skill-family contract` — splits the adopter's required
`<project-config>/` files by skill family (security workflow vs
PR triage and review). Adopters who use only one family can
delete the other family's scaffold;
- `How skills resolve <project-config>/ paths` — explains the
pure-text placeholder convention so adopters don't go hunting
for an env var or build step;
- `Keeping the submodule current` — preserves the existing
`git submodule update --init --recursive` post-merge-hook
guidance.
- **`projects/_template/README.md`** — adds a `### PR triage and
review` subsection listing the four PR-skill scaffold files
(`pr-triage-config.md`, `pr-triage-comment-templates.md`,
`pr-triage-ci-check-map.md`, `pr-maintainer-review-criteria.md`)
with per-file purpose and which skills consume them. The
"Checklist after copying" splits into three groups (security
workflow / PR triage and review / common finishers) so adopters
who only use one family can skip the other group's checks.
doctoc TOCs regenerated.
Both surfaces carry the same disclaimer that the framework
currently embeds airflow-flavoured defaults inline in the PR-
skill supporting files; a follow-up PR completes the extraction.
Until then non-airflow adopters override by forking the relevant
supporting file into their own `.claude/skills/<skill-name>/`.
Generated-by: Claude Code (Claude Opus 4.7)
---
README.md | 112 +++++++++++++++++++++++++++++++++++++++----
projects/_template/README.md | 44 +++++++++++++++++
2 files changed, 146 insertions(+), 10 deletions(-)
diff --git a/README.md b/README.md
index 139dd79..d656da6 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,10 @@
- [State diagram](#state-diagram)
- [Label reference](#label-reference)
- [Adopting the framework](#adopting-the-framework)
+ - [Bootstrapping a new adopter](#bootstrapping-a-new-adopter)
+ - [Per-skill-family contract](#per-skill-family-contract)
+ - [How skills resolve `<project-config>/`
paths](#how-skills-resolve-project-config-paths)
+ - [Keeping the submodule current](#keeping-the-submodule-current)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -988,11 +992,99 @@ their per-project configuration alongside it under
`<project-config>/` (which resolves to `.apache-steward/` in the
adopter's tracker root).
-To bootstrap a new adopter, copy [`projects/_template/`](projects/_template/)
-into `<project-config>/` in your tracker repo, fill in the TODO
-placeholders, and point the framework's skills at it via the path
-resolution documented in
-[`AGENTS.md` — Placeholder
convention](AGENTS.md#placeholder-convention-used-in-skill-files).
+### Bootstrapping a new adopter
+
+Three one-time steps to integrate the framework into a new tracker
+repo:
+
+1. **Add the framework as a submodule** of your tracker repo at
+ `.apache-steward/apache-steward/`:
+
+ ```bash
+ cd path/to/your/tracker-repo
+ git submodule add https://github.com/apache/airflow-steward
.apache-steward/apache-steward
+ ```
+
+2. **Copy the [`projects/_template/`](projects/_template/) scaffold**
+ into `.apache-steward/`, then `grep -rn TODO .apache-steward/` to
+ find every placeholder you need to fill in. The required files
+ vary by which skill families you're adopting — see
+ [Per-skill-family contract](#per-skill-family-contract) below.
+
+ ```bash
+ cp -r .apache-steward/apache-steward/projects/_template/. .apache-steward/
+ ```
+
+3. **Symlink `.claude/skills/`** in your tracker repo to the
+ framework's skill directory, so Claude Code (or another
+ `SKILL.md`-aware agent) loads the framework's skills against the
+ adopter's project configuration:
+
+ ```bash
+ ln -s .apache-steward/apache-steward/.claude/skills .claude/skills
+ ```
+
+The framework's
+[`setup-verify-steward`](.claude/skills/setup-verify-steward/SKILL.md)
+skill checks each of these and reports `✓ done / ✗ missing /
+⚠ partial` for the adopter integration — run it after step 3 to
+confirm the install landed.
+
+### Per-skill-family contract
+
+The `<project-config>/` files an adopter needs to populate depend
+on which skill families they want to use. Pick the families that
+match your project's needs — adopters who only use one family can
+delete the other family's scaffold files from their
+`.apache-steward/` directory.
+
+#### Security workflow — Steps 1–16 lifecycle
+
+Every skill in the [Security workflow](#security-workflow)
+section above consults at least
+[`<project-config>/project.md`](projects/_template/project.md) for
+identity. Beyond that, each skill reads only the files it needs:
+canned responses, scope labels, milestone conventions,
+title-normalisation rules, security-model pointers, release-train
+roster, fix-workflow specifics. The adopter's *file-by-file* index
+is in
+[`projects/_template/README.md`](projects/_template/README.md) —
+copy that into your `<project-config>/` and fill in every `TODO`.
+
+#### PR triage and review
+
+The [PR triage and review](#pr-triage-and-review) skills consult
+four scaffold files for project-specific knobs:
+
+| File | Used by |
+|---|---|
+| [`pr-triage-config.md`](projects/_template/pr-triage-config.md) |
`pr-triage`, `pr-stats` |
+|
[`pr-triage-comment-templates.md`](projects/_template/pr-triage-comment-templates.md)
| `pr-triage` |
+| [`pr-triage-ci-check-map.md`](projects/_template/pr-triage-ci-check-map.md)
| `pr-triage` |
+|
[`pr-maintainer-review-criteria.md`](projects/_template/pr-maintainer-review-criteria.md)
| `pr-maintainer-review` |
+
+Each PR-skill's `SKILL.md` carries an `## Adopter configuration`
+section that documents which of these files it reads. The framework
+currently embeds airflow-flavoured defaults inline in the skills'
+supporting files; non-airflow adopters override by forking the
+relevant supporting file into their own
+`.claude/skills/<skill-name>/`. A follow-up PR will complete the
+extraction so the skills read exclusively from `<project-config>/`.
+
+### How skills resolve `<project-config>/` paths
+
+The framework uses a documented placeholder convention: the literal
+string `<project-config>/` in any skill file resolves to the
+directory containing the adopter's `project.md` — typically
+`.apache-steward/` in the tracker root. The substitution rule is
+documented in
+[`AGENTS.md` § Placeholder
convention](AGENTS.md#placeholder-convention-used-in-skill-files);
+it's a pure-text reference, no env-var or build step required. The
+adopter keeps the actual content gitignored at the adopter level if
+they want to (the framework itself is project-agnostic and ships no
+per-project content).
+
+### Keeping the submodule current
**Always run `git submodule update --init --recursive` after every
pull on the tracker repository.** A plain `git pull` on the tracker
@@ -1011,8 +1103,8 @@ SH
chmod +x .git/hooks/post-merge
```
-The framework's `setup-upgrade-steward` skill (in this repo's
-[`.claude/skills/setup-upgrade-steward/SKILL.md`](.claude/skills/setup-upgrade-steward/SKILL.md))
-upgrades the framework checkout itself; if the user is consuming
-the framework as a tracker submodule, the skill reminds them to
-follow up with submodule update on the parent tracker.
+The framework's
+[`setup-upgrade-steward`](.claude/skills/setup-upgrade-steward/SKILL.md)
+skill upgrades the framework checkout itself; if the user is
+consuming the framework as a tracker submodule, the skill reminds
+them to follow up with submodule update on the parent tracker.
diff --git a/projects/_template/README.md b/projects/_template/README.md
index 1312f9d..47498aa 100644
--- a/projects/_template/README.md
+++ b/projects/_template/README.md
@@ -11,6 +11,7 @@
- [CVE-allocation mechanics](#cve-allocation-mechanics)
- [Remediation workflow](#remediation-workflow)
- [Editorial + reporter-facing](#editorial--reporter-facing)
+ - [PR triage and review](#pr-triage-and-review)
- [Checklist after copying](#checklist-after-copying)
- [Cross-references](#cross-references)
@@ -87,14 +88,57 @@ the rest.
| [`naming-conventions.md`](naming-conventions.md) | Project-specific
editorial rules. Keep only the ones that differ from the generic rules in
`../../AGENTS.md`. |
| [`canned-responses.md`](canned-responses.md) | Reusable reporter-facing
reply templates. |
+### PR triage and review
+
+These files configure the
+[`pr-triage`](../../.claude/skills/pr-triage/SKILL.md),
+[`pr-stats`](../../.claude/skills/pr-stats/SKILL.md), and
+[`pr-maintainer-review`](../../.claude/skills/pr-maintainer-review/SKILL.md)
+skills. Adopters who only use the security skills can delete these
+four files; adopters running maintainer-side PR-queue management
+fill them in.
+
+| File | Purpose |
+|---|---|
+| [`pr-triage-config.md`](pr-triage-config.md) | Committers team handle,
area-label prefix, project-specific labels (`ready for maintainer review`,
etc.), grace windows. Used by `pr-triage` and `pr-stats`. |
+| [`pr-triage-comment-templates.md`](pr-triage-comment-templates.md) |
Comment-body URLs (PR quality criteria, two-stage triage rationale),
AI-attribution footer wording, project display name. Used by `pr-triage`. |
+| [`pr-triage-ci-check-map.md`](pr-triage-ci-check-map.md) | CI-check name
pattern → category name + doc-URL mapping for the violations comment. Used by
`pr-triage`. |
+| [`pr-maintainer-review-criteria.md`](pr-maintainer-review-criteria.md) |
List of project's review-criteria source files (repo-wide AGENTS.md,
code-review docs, per-area AGENTS.md), security-model calibration doc,
backport-branch pattern, section-anchor URLs. Used by `pr-maintainer-review`. |
+
+> The framework currently ships with airflow-flavoured defaults
+> inline in the supporting files of each PR-skill (e.g.
+>
[`pr-triage/comment-templates.md`](../../.claude/skills/pr-triage/comment-templates.md)
+> embeds airflow's PR-quality-criteria URL). A follow-up PR will
+> complete the extraction so the skills read exclusively from
+> `<project-config>/`. Until then, non-airflow adopters override by
+> forking the relevant supporting file into their own
+> `.claude/skills/<skill-name>/`. Each PR-skill's `SKILL.md`
+> documents the override path in its `Adopter configuration`
+> section.
+
## Checklist after copying
- [ ] `cp -R projects/_template projects/<name>` done.
- [ ] Every `TODO` in `project.md` resolved (grep: `grep -n TODO
projects/<name>/project.md`).
+
+**Security workflow** (delete this group if not using the security
+skills):
+
- [ ] `scope-labels.md` lists at least one scope label (exactly-one-of rule).
- [ ] `security-model.md` points at the project's authoritative Security-Model
URL.
- [ ] `release-trains.md` has at least one current release branch + its RM.
- [ ] `canned-responses.md` has at least the *"Confirmation of receiving the
report"* template filled in (the `security-import-issues` skill sends this
verbatim).
+
+**PR triage and review** (delete this group if not using the
+`pr-*` skills):
+
+- [ ] `pr-triage-config.md` — committers team handle and area-label prefix
filled in.
+- [ ] `pr-triage-comment-templates.md` — `<quality_criteria_url>`,
`<two_stage_triage_rationale_url>`, and `<project_display_name>` filled in.
+- [ ] `pr-triage-ci-check-map.md` — at least one CI-check pattern row filled
in (or the catch-all row pointing at the project's static-checks doc).
+- [ ] `pr-maintainer-review-criteria.md` — at least one repo-wide
review-criteria source file declared.
+
+**Common finishers**:
+
- [ ] `config/active-project.md` updated to the new directory name if this
working tree should target the new project.
- [ ] Root `README.md` *"Current projects"* table updated with a row for the
new project + a link to this `README.md`.
- [ ] `prek run --all-files` passes.
