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 60712b9 setup-steward: generic _template/pr-management-config +
upgrade hygiene check (#280)
60712b9 is described below
commit 60712b94028bbf42018e9bf36fef4781495632d5
Author: Jarek Potiuk <[email protected]>
AuthorDate: Mon May 25 18:16:02 2026 +0200
setup-steward: generic _template/pr-management-config + upgrade hygiene
check (#280)
The framework's projects/_template/pr-management-config.md was
seeded from one adopter's config — title hardcoded to that
project's name, `committers_team` set to a concrete org/team
slug, grace-window prose calibrated to that one project's
traffic. Replace the project-identity bits with placeholders
(`<Project Name>`, `<github-org>/<committers-team-slug>`) plus
an "Example: …" annotation. Suggested-default label strings
stay; grace-window numbers stay as defaults but get a "scale
up for lower traffic" note instead of an adopter-specific
calibration line.
Add Step 6d to setup-steward/upgrade.md: a defensive hygiene
pass that scans every file under projects/_template/ for
adopter-specific signals (project names in H1s, hardcoded
URLs, real committer-team slugs, calibration prose) and
surfaces ⚠ rows in the upgrade summary. Purely advisory —
never modifies the snapshot, never auto-fixes; the operator
decides whether to file a tracking issue.
First of a series — projects/_template/pr-management-triage-
ci-check-map.md has the same problem and will follow in a
separate PR.
Generated-by: Claude (Opus 4.7)
---
.claude/skills/setup-steward/upgrade.md | 63 ++++++++++++++++++++++++++++++
projects/_template/pr-management-config.md | 35 +++++++++++------
2 files changed, 86 insertions(+), 12 deletions(-)
diff --git a/.claude/skills/setup-steward/upgrade.md
b/.claude/skills/setup-steward/upgrade.md
index 2544645..93d630b 100644
--- a/.claude/skills/setup-steward/upgrade.md
+++ b/.claude/skills/setup-steward/upgrade.md
@@ -470,6 +470,63 @@ upgrade — secure-agent setup is independent of framework
upgrade). The recap row in Step 8's output goes under a new
`Sandbox allowlist:` section.
+## Step 6d — Audit framework template genericity
+
+A defensive hygiene pass over the framework's
+`<snapshot-dir>/projects/_template/` directory. Templates
+are meant to be **project-agnostic scaffolds** that adopters
+copy and customise — they should contain placeholders
+(`<Project Name>`, `<github-org>/<team-slug>`, etc.),
+generic examples, and no hardcoded project identity.
+
+In practice the framework's `_template/` files have at
+times been seeded from one specific adopter's data
+(originally the project the framework grew out of) and
+not always generalised back. This step surfaces the
+residue so it can be filed as an issue against
+`apache/airflow-steward` and fixed upstream.
+
+For each file under `<snapshot-dir>/projects/_template/`,
+scan for adopter-specific signals:
+
+- **Hardcoded project names in titles or prose** — H1
+ headings, doc body text, calibration sentences. A
+ genuine template starts with `# TODO: <Project Name> —
+ ...` or uses a `<PROJECT>` placeholder; if a concrete
+ name appears there instead, that is the residue.
+- **Hardcoded URLs** pointing at a specific adopter —
+ `github.com/<org>/<repo>/...` paths in body text,
+ mailing-list addresses tied to a specific TLD,
+ project-specific chat URLs. Template URLs should be
+ `<placeholder>` or annotated "Example: …".
+- **Hardcoded org / team identifiers** — committer-team
+ slugs (e.g. `<org>/<team>-committers`), real maintainer
+ handles, project-specific issue-tracker keys. Same
+ rule: placeholder, or marked as an example.
+- **Project-specific calibration prose** — references
+ to contributor counts, specific issue numbers,
+ incident postmortems, or other particulars an
+ arbitrary adopter wouldn't share.
+
+Surface the findings as a `Framework templates:` block in
+the upgrade summary (see [Step 8 output](#output-to-the-user))
+— one ⚠ row per file with a short summary of what looks
+adopter-specific. **Do not modify the snapshot** (it is
+read-only per
+[`SKILL.md` Golden rule 1](SKILL.md#golden-rules)). The
+recap is purely advisory; the operator decides whether to
+open a tracking issue / PR against
+`apache/airflow-steward`.
+
+The check is intentionally heuristic — false positives are
+acceptable because the cost is one line in the summary, not
+a blocked upgrade. False negatives are also acceptable; the
+operator's read of the upgrade summary is the real signal.
+**Never attempt to auto-fix.**
+
+If every template scans clean, surface the section as
+`✓ all framework templates look generic`.
+
## Step 7 — Update `<local-lock>`
Write the new local lock with the values captured in Step
@@ -538,6 +595,12 @@ Overrides:
⚠ <list of overrides flagged for re-anchoring> (open the
file and update against the new framework structure)
+Framework templates (projects/_template/):
+ ✓ all templates look generic OR
+ ⚠ <_template/foo.md> (e.g. H1 title hardcoded to a specific
project name)
+ ⚠ <_template/bar.md> (e.g. `committers_team` set to a concrete
org/team without placeholder)
+ → file an issue against apache/airflow-steward to upstream a fix
+
Recommended follow-ups:
- Run /setup-isolated-setup-update if the secure-setup blast
radius (settings.json, agent-isolation/, pinned-versions.toml)
diff --git a/projects/_template/pr-management-config.md
b/projects/_template/pr-management-config.md
index 9f6a6fb..d317be9 100644
--- a/projects/_template/pr-management-config.md
+++ b/projects/_template/pr-management-config.md
@@ -2,7 +2,7 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
-- [Apache Airflow — pr-management-triage
configuration](#apache-airflow--pr-management-triage-configuration)
+- [TODO: `<Project Name>` — pr-management-triage
configuration](#todo-project-name--pr-management-triage-configuration)
- [Identifiers](#identifiers)
- [Project-specific labels](#project-specific-labels)
- [Grace windows](#grace-windows)
@@ -12,21 +12,25 @@
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->
-# Apache Airflow — pr-management-triage configuration
+# TODO: `<Project Name>` — pr-management-triage configuration
This file is the **per-project configuration** for the
[`pr-management-triage`](../../.claude/skills/pr-management-triage/SKILL.md)
skill.
-It contains the concrete values for the Apache Airflow project.
-New adopters should copy this file into their own
+It holds the concrete values for your adopter project.
+
+Copy this file into your own
`<project-config>/pr-management-config.md` and replace every
-Airflow-specific value with their project's equivalents.
+`<placeholder>` with your project's value. The suggested label
+strings and grace-window defaults below are reasonable starting
+points — keep them as-is or override with your project's
+existing conventions.
## Identifiers
| Key | Value | Used by |
|---|---|---|
-| `committers_team` | `apache/airflow-committers` | `classify-and-act.md` row
F5b — team-mention detection. Used to recognise PR comments that `@`-mention
the project's committers as a maintainer-to-maintainer ping. |
-| `area_label_prefix` | `area:` | `classify-and-act.md`, `pr-management-stats`
— area-label grouping. |
+| `committers_team` | `<github-org>/<committers-team-slug>` |
`classify-and-act.md` row F5b — team-mention detection. Used to recognise PR
comments that `@`-mention the project's committers as a
maintainer-to-maintainer ping. Example: `apache/airflow-committers`. |
+| `area_label_prefix` | `area:` | `classify-and-act.md`, `pr-management-stats`
— area-label grouping. Adjust to the prefix your project uses for area labels
(e.g. `comp:`, `module:`), or leave blank if your project doesn't group PRs by
area. |
## Project-specific labels
@@ -35,18 +39,25 @@ Labels the skill applies or watches for. Each row maps a
generic
If the project doesn't have a given concept, leave the value blank
and the skill will skip that row of decision-table actions.
-| Concept | Label | Notes |
+The labels below are **suggested defaults** — readable English
+strings that work for most projects. Override with your project's
+existing label names if any are already in use.
+
+| Concept | Suggested label | Notes |
|---|---|---|
| `ready_for_maintainer_review` | `ready for maintainer review` | Applied by
the `mark-ready` action; used by `pr-management-code-review` as a default
selector. |
| `quality_violations_close` | `closed because of multiple quality violations`
| Applied when a PR is closed for failing the project's PR quality criteria
after multiple opportunities to fix. |
| `suspicious_changes` | `suspicious changes detected` | Applied to
first-time-contributor workflow approvals where the diff looks suspicious
(binary blobs, unrelated CI changes, etc.). |
-| `work_in_progress` | | Airflow does not use a dedicated WIP label; the skill
relies on draft status instead. |
+| `work_in_progress` | | Leave blank if your project doesn't use a dedicated
WIP label (the skill relies on draft status instead); fill in the label name if
your project does. |
## Grace windows
-Tunable thresholds. These values were calibrated for Airflow's
-contributor traffic (~50–100 open PRs, triage sweep every 1–2
-days).
+Tunable thresholds. The defaults below are sized for a project
+with **~50–100 open PRs and a triage sweep every 1–2 days**.
+Scale them up for projects with lower contributor traffic — less
+frequent sweeps imply longer grace windows so the skill doesn't
+fire stale-action proposals on PRs the maintainer hasn't had a
+chance to look at yet.
| Concept | Default | Project value |
|---|---|---|
