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 1218969 feat(github): add issue and PR templates aligned with
CONTRIBUTING.md (#324)
1218969 is described below
commit 12189697fc315cac9f2190035f3597c4546ad536
Author: Jarek Potiuk <[email protected]>
AuthorDate: Tue May 26 21:07:31 2026 +0200
feat(github): add issue and PR templates aligned with CONTRIBUTING.md (#324)
Why: the framework didn't have issue or PR templates, so every new
issue and PR re-invented its own shape. That's particularly costly
for a framework with an intent-first authoring loop — vague issues
turn into vague agentic conversations that don't converge, and PRs
without an explicit RFC-AI-0004 compliance pass miss principles a
reviewer would otherwise catch.
The templates operationalise CONTRIBUTING.md's guidance:
- `bug_report.yml` — what's broken, which layer, repro, expected vs
actual. Calls out that an eval fixture is the highest-signal
evidence for a skill-behaviour bug.
- `change_proposal.yml` — intent-first by design. Required fields are
*what* + *why* + which layer; *how* is explicitly out of scope for
the issue and left to the agentic loop on the PR. Optional
boundary-conditions and out-of-scope fields surface edges up front,
saving a round-trip during implementation.
- `config.yml` — disables blank issues; routes open-ended questions
to Discussions; routes adopter security vulnerabilities to the
adopter project's `security@` list per ASF policy (NOT here).
- `PULL_REQUEST_TEMPLATE.md` — the ## Summary + ## Test plan shape
documented in CONTRIBUTING.md, plus a Type-of-change checklist
scoped to the framework's layer map and an RFC-AI-0004 compliance
checklist (six principles → six checkboxes). The eval-fixture
requirement for skill behaviour changes is called out explicitly.
Companion change to `.pre-commit-config.yaml`: add the PR template
to the doctoc exclude list. GitHub pre-populates a new PR
description with the template verbatim, so a doctoc-generated TOC
becomes per-PR noise the contributor has to delete by hand.
---
.github/ISSUE_TEMPLATE/bug_report.yml | 66 ++++++++++++++++++++++++++++
.github/ISSUE_TEMPLATE/change_proposal.yml | 69 ++++++++++++++++++++++++++++++
.github/ISSUE_TEMPLATE/config.yml | 11 +++++
.github/PULL_REQUEST_TEMPLATE.md | 69 ++++++++++++++++++++++++++++++
.pre-commit-config.yaml | 5 ++-
5 files changed, 219 insertions(+), 1 deletion(-)
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml
b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..d7b23b6
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+# https://www.apache.org/licenses/LICENSE-2.0
+
+name: Bug report
+description: Something in the framework doesn't behave as its SKILL.md /
tool.md / RFC says it should.
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to file a bug. Before submitting:
+
+ - Read the relevant `SKILL.md` or `tool.md` — that contract is
authoritative. If the bug is a *contract* problem (the doc says one thing, the
implementation does another), say which one is wrong.
+ - Check the open issues for a duplicate.
+ - If the bug is in a skill's behaviour, the eval fixture you'd add as
a regression test is the highest-signal evidence you can include. See
`tools/skill-evals/README.md` for the fixture format.
+
+ - type: textarea
+ id: what
+ attributes:
+ label: What's broken
+ description: One or two sentences. The bug, not the diagnosis.
+ placeholder: |
+ e.g. `security-issue-triage` step 4 emits a `_No response_` literal
for the public-advisory-url field when the reporter included a draft GHSA URL
inline.
+ validations:
+ required: true
+
+ - type: textarea
+ id: where
+ attributes:
+ label: Which layer
+ description: Where in the tree does the bug live? Include the file path
if you have it.
+ placeholder: |
+ e.g. `.claude/skills/security-issue-triage/step-4-classify.md`
+ or `tools/vulnogram/generate-cve-json/src/...`
+ validations:
+ required: true
+
+ - type: textarea
+ id: repro
+ attributes:
+ label: How to reproduce
+ description: |
+ Minimum steps. For a skill bug, the input that triggers the wrong
output (an eval-fixture-shaped block is ideal). For a Python / Groovy bug, the
command + the error.
+ validations:
+ required: true
+
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected vs actual
+ description: What you expected to happen; what actually happened. Quote
the relevant SKILL.md / tool.md / RFC line if there's a contract violation.
+ validations:
+ required: true
+
+ - type: textarea
+ id: scope
+ attributes:
+ label: Surface area (optional)
+ description: Other skills / tools / files this might also affect. Helps
whoever picks this up scope the change correctly.
+
+ - type: textarea
+ id: env
+ attributes:
+ label: Environment (optional)
+ description: |
+ Claude Code (or other harness) version, OS, sandbox state
(`/setup-isolated-setup-verify` output), anything in `<project-config>/` that
might matter. Skip if not relevant.
diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yml
b/.github/ISSUE_TEMPLATE/change_proposal.yml
new file mode 100644
index 0000000..e9f031c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yml
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+# https://www.apache.org/licenses/LICENSE-2.0
+
+name: Change proposal
+description: New skill, new tool bridge, behaviour change to an existing one,
doc improvement, or RFC. Intent-first.
+labels: ["enhancement"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ This template is **intent-first** by design. Tell us *what* you want
and *why* — let the agent (or a maintainer) figure out *how*. See
[CONTRIBUTING.md → Authoring with an
agent](../blob/main/CONTRIBUTING.md#authoring-with-an-agent) for the loop.
+
+ Don't worry about writing a complete spec. The discussion in this
issue plus the agentic loop on the eventual PR are where the design converges.
A sharp two-sentence intent is more useful than a vague half-built design.
+
+ - type: textarea
+ id: what
+ attributes:
+ label: What should happen
+ description: One or two sentences. Behaviour-shaped, not
implementation-shaped.
+ placeholder: |
+ e.g. `security-issue-triage` should flag reports that arrive with a
draft GHSA URL in the body and route them to the pre-coordinated-by-CNA branch
of the triage tree.
+ validations:
+ required: true
+
+ - type: textarea
+ id: why
+ attributes:
+ label: Why
+ description: The motivation, in concrete terms. A constraint, a workflow
gap, a regression, a principle from RFC-AI-0004 — whatever the actual reason is.
+ placeholder: |
+ e.g. Pre-coordinated GHSA reports are treated as fresh inbound today,
which wastes a triage cycle and confuses the reporter when our acknowledgement
asks them to provide information their CNA has already published.
+ validations:
+ required: true
+
+ - type: dropdown
+ id: layer
+ attributes:
+ label: Which layer
+ description: Best guess — a maintainer or the agent can re-route during
triage.
+ options:
+ - Skill (`.claude/skills/<name>/`)
+ - Tool / bridge (`tools/<system>/`)
+ - Python package (`tools/*/` with `pyproject.toml`)
+ - Groovy reference impl
+ - Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
+ - Documentation (`docs/`, `README.md`, `CONTRIBUTING.md`)
+ - Project template (`projects/_template/`)
+ - Other / unsure
+ validations:
+ required: true
+
+ - type: textarea
+ id: edges
+ attributes:
+ label: Boundary conditions (optional)
+ description: |
+ Edge cases worth raising up front — what should happen if input X is
empty, malformed, contradictory, or already pre-existing. The agent will probe
these during implementation; flagging the obvious ones here saves a round-trip.
+
+ - type: textarea
+ id: out-of-scope
+ attributes:
+ label: Out of scope (optional)
+ description: Things you're *not* proposing, to keep the discussion
focused. Especially useful for changes that touch a sensitive area (security,
privacy-LLM, sandbox, write-access discipline).
+
+ - type: textarea
+ id: references
+ attributes:
+ label: References (optional)
+ description: Related issues, prior PRs, RFC sections, upstream API docs
— anything that gives whoever picks this up a head start.
diff --git a/.github/ISSUE_TEMPLATE/config.yml
b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..7a00c07
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# https://www.apache.org/licenses/LICENSE-2.0
+
+blank_issues_enabled: false
+contact_links:
+ - name: Discussion
+ url: https://github.com/apache/airflow-steward/discussions
+ about: Open-ended questions, ideas, "is this in scope?" — use Discussions,
not an issue.
+ - name: Security vulnerability in a project that uses this framework
+ url: https://www.apache.org/security/
+ about: Report to that project's `security@` list per ASF policy. Do NOT
file a public issue here.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..cfcff21
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,69 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+## Summary
+
+<!--
+1-3 bullets: what changed and why. The "why" is what reviewers care
+about most — a one-line summary of the motivation beats a paragraph
+restating the diff.
+-->
+
+-
+
+## Type of change
+
+<!-- Tick all that apply. -->
+
+- [ ] Skill change (`.claude/skills/<name>/`) — eval fixtures updated below
+- [ ] Tool / bridge contract (`tools/<system>/*.md`)
+- [ ] Python package (`tools/*/` with `pyproject.toml`)
+- [ ] Groovy reference impl
+- [ ] Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
+- [ ] Documentation (`docs/`, `README.md`, `CONTRIBUTING.md`)
+- [ ] Project template (`projects/_template/`)
+- [ ] CI / dev loop (`prek`, workflows, validators)
+- [ ] Other:
+
+## Test plan
+
+<!--
+How you verified the change. Be specific. The reviewer reads this to
+decide what to spot-check vs trust. Empty "ran the tests" doesn't help.
+-->
+
+- [ ] `prek run --all-files` passes
+- [ ] For Python packages touched: `uv run pytest` / `ruff check` / `mypy`
passes
+- [ ] For Groovy bridges touched: command-line invocation tested end-to-end
+- [ ] For skill changes: eval suite passes for the affected skill
+ (`PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner
tools/skill-evals/evals/<skill>/`)
+- [ ] For skill *behaviour* changes: a new or updated eval fixture is included
in this PR
+ (a regression test for the bug fixed / the behaviour added — see
CONTRIBUTING.md)
+- [ ] Other:
+
+## RFC-AI-0004 compliance
+
+<!--
+Tick the principles the change touches. Skip rows that don't apply.
+RFC-AI-0004 is the framework's constitution — see
+docs/rfcs/RFC-AI-0004.md.
+-->
+
+- [ ] **HITL** — any new mutation is gated on explicit user confirmation
+- [ ] **Sandbox** — no new unrestricted host access; network reach declared in
the adapter
+- [ ] **Vendor neutrality** — placeholders (`<PROJECT>`, `<tracker>`,
`<upstream>`, `<security-list>`) used in all skill / tool prose (the
`check-placeholders` prek hook is the mechanical gate)
+- [ ] **Conversational + correctable** — agentic-override path documented if
behaviour is adopter-tunable
+- [ ] **Write-access discipline** — no autonomous outbound messages; drafts
only, sent on confirmation
+- [ ] **Privacy LLM** — private content does not reach a non-approved LLM;
redactor invoked where needed
+
+## Linked issues
+
+<!-- e.g. Closes #NNN, Refs #NNN. List every related issue. -->
+
+## Notes for reviewers (optional)
+
+<!--
+Anything specific you want the reviewer to look at. Areas of uncertainty.
+Trade-offs you considered and rejected. Decisions that the agent and you
+disagreed on during the authoring loop.
+-->
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4fb3888..887e9af 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -43,7 +43,10 @@ repos:
# the first thing in the file, which is incompatible with doctoc
# inserting a TOC block at the top. Also skip skill-evals fixture and
# README files — short, single-purpose docs that don't warrant a TOC.
- exclude:
^(\.claude/skills/.*|tools/vulnogram/generate-cve-json/SKILL\.md|tools/skill-evals/.*)$
+ # Skip the PR template — GitHub pre-populates a new PR description
+ # with the template verbatim, so a TOC block becomes per-PR noise the
+ # contributor has to delete by hand.
+ exclude:
^(\.claude/skills/.*|tools/vulnogram/generate-cve-json/SKILL\.md|tools/skill-evals/.*|\.github/PULL_REQUEST_TEMPLATE\.md)$
args:
- "--maxlevel"
- "3"
