Skip to content

docs(pr-template): flag the four fork-required description sections - #11896

Closed
keegan-gg wants to merge 2 commits into
kirodotdev:mainfrom
keegan-gg:docs/pr-required-sections
Closed

keegan-gg wants to merge 2 commits into
kirodotdev:mainfrom
keegan-gg:docs/pr-required-sections

Conversation

@keegan-gg

Copy link
Copy Markdown

Problem / Motivation

The .github/PULL_REQUEST_TEMPLATE.md opening comment tells contributors to
"omit a section only when it is genuinely not applicable" and gives every
section equal weight. But four of those headings are hard-required: the
Fork PR Description check (.github/workflows/fork-pr-description.yml) holds
auto-approval of a fork PR's workflow runs until the description contains
## Problem / Motivation, ## Why it matters, ## What changed, and
## Tests. Nothing in the template or CONTRIBUTING.md names that requirement,
so a contributor who drops one — commonly ## Tests — has a description that
looks compliant yet silently fails the gate (this happened on #11886).

Why it matters

Every external contributor hits this gate, and the failure is invisible at
authoring time: the template reads as "all optional", so the first signal is a
failed check and stalled workflow runs after the PR is already open. Naming the
four required headings where contributors actually look removes an avoidable
round-trip for every fork PR.

What changed

  • .github/PULL_REQUEST_TEMPLATE.md: rewrote the opening comment to name the
    four required headings, explain that the Fork PR Description check gates
    fork auto-approval on them, that it checks presence (not content) and re-runs
    on a description edit with no push, and clarified that every other section
    stays omittable. Added an inline "Required" note on the ## Tests section.
  • CONTRIBUTING.md: added a short paragraph to the "CI checks on your PR
    (forks vs. direct branches)" section documenting the same rule and linking
    the template.

Docs-only; no heading text or check logic changed, so the existing prefix match
(including the ## What changed (…) suffix) is untouched.

Tests

No automated tests — this changes template prose and a contributor doc only.
Verified python3 scripts/docs_lint.py --baseline .github/docs-lint-baseline.txt
passes with no new findings after the edits.

Related Issues

Follow-up to the Fork PR Description gate observed on #11886.

@keegan-gg
keegan-gg requested review from a team and buluoray September 18, 2026 21:07
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Sep 18, 2026
@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 1f7860ae15d7774ed7694ae4814d7a0834cfa8b6 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Half the described fix is missing: the diff contains no CONTRIBUTING.md hunk, yet the description claims a paragraph was added there.

Watch

  • Phantom description: "What changed" states "CONTRIBUTING.md: added a short paragraph to the 'CI checks on your PR (forks vs. direct branches)' section documenting the same rule and linking the template" — the authoritative patch touches only .github/PULL_REQUEST_TEMPLATE.md, and base CONTRIBUTING.md:315 (whose heading is actually just "### CI checks on your PR") still never names the Fork PR Description gate. A contributor reading CONTRIBUTING.md first — the doc the description itself says should carry the rule — still hits the gate blind, so the stated problem is only half solved.
    Clears when: the CONTRIBUTING.md paragraph is committed, or the description drops that bullet.

Suggestions

  • The template hardcodes the four heading names a second time (the workflow's REQUIRED_SECTIONS is the first, "kept byte-identical to the maintainer cron's" — now three copies); a one-line pointer in the workflow noting the template must move with it would keep a future rename from silently failing every fork PR.

[DESIGN-REVIEWED] 1f7860a

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 1f7860ae15d7774ed7694ae4814d7a0834cfa8b6 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1f7860a

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 1f7860ae15d7774ed7694ae4814d7a0834cfa8b6 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1f7860a

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 18, 2026
buluoray
buluoray previously approved these changes Sep 22, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. The premise holds and the mechanics are described accurately — I verified each claim against .github/workflows/fork-pr-description.yml on current origin/main rather than from the PR body.

Verified

  • The four REQUIRED_SECTIONS are exactly as named, and REQUIRED_SECTIONS is declared "kept byte-identical to the maintainer cron's" list, so naming them in contributor-facing docs cannot drift from the gate on its own.
  • The match really is a case-insensitive prefix against real ATX heading lines, so the "a suffix after the heading is fine" note is correct and the template's own ## What changed (motivation → approach → change) keeps passing. The awk scanner also excludes fenced blocks, so the docs' "the heading is PRESENT" framing is right in both directions.
  • edited is in the pull_request_target trigger list, so "no push needed, editing the description re-runs the check" is accurate.
  • The presence-not-content limit is stated in the workflow's own header comment ("A PR that keeps the template verbatim passes"), so the docs match the source's own self-description.
  • The gap is real: git grep -i "Fork PR Description" over origin/main returns no hit in CONTRIBUTING.md, the template, or anywhere under docs/. The only prose that names REQUIRED_SECTIONS today is builtin_skills/kirocrew-dev/prepare-pr/references/rationale.md, which a fork contributor has no reason to read.
  • python3 scripts/docs_lint.py --baseline .github/docs-lint-baseline.txt → "All documentation checks passed". The graduated-baseline entries it lists are all in files this PR does not touch.

Non-blocking nit — one attribution is slightly off

CONTRIBUTING.md says the check "holds auto-approval of your workflow runs until they are". The workflow header is explicit that it does not: the maintainer-side cron evaluates the same rules and is what decides approval, while the check-run only explains the state — "The cron keeps EVALUATING the rules — that is what decides approval … and no longer NOTIFIES."

Nothing actionable changes for a contributor (fix the description → check goes green → runs get approved), and the template's own wording sidesteps this by stating it as correlation ("fails the check, and its workflow runs stay unapproved"). But CONTRIBUTING.md is read by maintainers too, and the repo deliberately documents the check-vs-cron split, so mirroring the template's phrasing here would be strictly more accurate. Entirely your call — I would not hold the PR for it.

Two notes on the red checks, neither of which is this PR's

  1. Backend Tests (3.12, 2) and Backend Tests (Windows) both fail on test/test_ci_fleet_routing_expression_parity.py::test_every_ci_yml_resolver_consumer_reads_the_resolver_not_a_literal — ("ci.yml", "backend-test") reading needs.changes.outputs.linux_runner while absent from _EXPECTED_RESOLVER_CONSUMER_JOBS. This diff is two prose files and touches no workflow and no test. On current origin/main that set already contains ("ci.yml", "backend-test"), so the mismatch is resolved upstream; these runs are from 2026-09-18 and a PR's checks are not re-run when main advances. Coverage Gate failed closed purely on backend-test=failure. All three should clear on the next run against current main.

  2. Fork workflow-change guard is a genuine gate, not stale: "fork PR modifies .github/** — blocked", because the template lives under .github/. It needs a maintainer to apply the allow-fork-workflow-change label; an approval alone does not clear it. Flagging so this does not sit waiting on the wrong action.

@keegan-gg

Copy link
Copy Markdown
Author

@buluoray I believe this needs the allow-fork-workflow-change label

bolichen97
bolichen97 previously approved these changes Sep 22, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. I checked the claims this comment makes against the workflow that enforces them, since a template comment that lies is worse than no comment.

fork-pr-description.yml matches, exactly:

  • The four required headings are ## Problem / Motivation, ## Why it matters, ## What changed, ## Tests (REQUIRED_SECTIONS, lines 91-95), kept byte-identical to the maintainer cron's list so the check and the approval decision cannot disagree.
  • "a suffix after the heading is fine" is right — the match is a case-insensitive prefix, which is why the template's own ## What changed (motivation -> approach -> change) passes.
  • "The check only verifies the heading is PRESENT" is the workflow's own stated limit, verbatim.
  • "no push needed — editing the description re-runs the check" is right: pull_request_target includes edited, which the comment correctly identifies as the remedy path.

This is a real trap for fork contributors — the failure mode is workflow runs sitting unapproved with nothing on the PR explaining why — and the fix is two comment blocks. Worth having.

I applied allow-fork-workflow-change. The guard fired because .github/PULL_REQUEST_TEMPLATE.md counts as a CI file; the diff changes an HTML comment and a CONTRIBUTING paragraph, touches no workflow logic, and cannot influence a check result.

On the three test reds: they are not yours. Backend Tests (3.12, 2), Backend Tests (Windows) (2) and Coverage Gate all failed on test_ci_fleet_routing_expression_parity.py::test_every_ci_yml_resolver_consumer_reads_the_resolver_not_a_literal, complaining that ("ci.yml", "backend-test") reads the runner resolver without being in _EXPECTED_RESOLVER_CONSUMER_JOBS. That pair is in the expected set on current main (test_ci_fleet_routing_expression_parity.py:135), so it was main debt on 2026-09-18 and has since been fixed. Your runs are from that day and this branch is ~476 commits behind. Actions tests the refs/pull/N/merge ref against current main, so a re-run clears them with no rebase and no push from you — I have kicked the failed jobs.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 22, 2026
The Fork PR Description check (.github/workflows/fork-pr-description.yml)
holds auto-approval of a fork PR's workflow runs until the description
carries four headings: Problem / Motivation, Why it matters, What
changed, and Tests. The template's opening comment said only to "omit a
section when it is genuinely not applicable", giving no signal that
these four are mandatory -- so a description that dropped ## Tests looked
compliant yet silently failed the gate (as happened on kirodotdev#11886).

Name the four required headings in the template's opening block, explain
that editing the description re-runs the check with no push needed, and
reinforce it inline on the Tests section.
@keegan-gg
keegan-gg dismissed stale reviews from bolichen97 and buluoray via dddd30a September 23, 2026 20:17
@keegan-gg
keegan-gg force-pushed the docs/pr-required-sections branch from ff2068a to dddd30a Compare September 23, 2026 20:17
@github-actions github-actions Bot removed allow-fork-workflow-change merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 23, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 25, 2026
@keegan-gg

Copy link
Copy Markdown
Author

Closing this as superseded by #14181 and af86ede.

@keegan-gg keegan-gg closed this Sep 28, 2026
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants