From b7bfc00d5356236cbd17a36662e4c9e63171c373 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Sat, 2 May 2026 18:10:04 +0200 Subject: [PATCH] docs: extend Adopting the framework section for PR-skill adopter contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 `/` 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 / 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//`. 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 139dd7973..d656da627 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 `/` paths](#how-skills-resolve-project-config-paths) + - [Keeping the submodule current](#keeping-the-submodule-current) @@ -988,11 +992,99 @@ their per-project configuration alongside it under `/` (which resolves to `.apache-steward/` in the adopter's tracker root). -To bootstrap a new adopter, copy [`projects/_template/`](projects/_template/) -into `/` 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 `/` 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.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 `/` 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//`. A follow-up PR will complete the +extraction so the skills read exclusively from `/`. + +### How skills resolve `/` paths + +The framework uses a documented placeholder convention: the literal +string `/` 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 1312f9d44..47498aadf 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 +> `/`. Until then, non-airflow adopters override by +> forking the relevant supporting file into their own +> `.claude/skills//`. Each PR-skill's `SKILL.md` +> documents the override path in its `Adopter configuration` +> section. + ## Checklist after copying - [ ] `cp -R projects/_template projects/` done. - [ ] Every `TODO` in `project.md` resolved (grep: `grep -n TODO projects//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` — ``, ``, and `` 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.