diff --git a/.github/workflows/script-tests.yml b/.github/workflows/script-tests.yml index c402ccc..6816c8e 100644 --- a/.github/workflows/script-tests.yml +++ b/.github/workflows/script-tests.yml @@ -17,7 +17,14 @@ jobs: matrix: os: [ubuntu-latest, macos-latest] python: ["3.9", "3.x"] + # actions/setup-python has no Python 3.9 build for Ubuntu 26.04, the + # image behind ubuntu-latest. 3.9 is end of life, so none will come. + exclude: + - os: ubuntu-latest + python: "3.9" include: + - os: ubuntu-24.04 + python: "3.9" # The interpreter that ships with the developer tools of macOS. - os: macos-latest python: system diff --git a/skills/opening-a-pull-request/SKILL.md b/skills/opening-a-pull-request/SKILL.md index 2fd583a..e99c418 100644 --- a/skills/opening-a-pull-request/SKILL.md +++ b/skills/opening-a-pull-request/SKILL.md @@ -101,7 +101,7 @@ Opening and flipping aren't the only moments the body has to be true. Commits la The mechanic: -1. **Rewrite the affected sections** from the template the PR already uses (draft or ready) so they match the diff. Leave the opening issue-link keyword and the title unchanged — neither the linkage nor the type/area changed. Do not flip the lifecycle state; this is a body edit, not a `gh pr ready`. +1. **Rewrite the affected sections** from the template the PR already uses (draft or ready) so they describe what the branch does now. "Match the diff" means the body's claims hold for the branch, not that the body retells the diff: each new commit's change is written as the template asks, as a difference a user or an operator will notice, with what it replaces. Leave the opening issue-link keyword and the title unchanged — neither the linkage nor the type/area changed. Do not flip the lifecycle state; this is a body edit, not a `gh pr ready`. 2. **Confirm the exact body** (§Core principle) — paste it inline under an "About to update #'s body to match the diff — body only, PR stays as-is. Confirm?" line, and wait for an explicit yes. Under a standing grant for PR body edits, skip the prompt and show the new body in your reply. 3. **Run the single mutation** once confirmed: `gh pr edit --body "$(cat <<'EOF' … EOF)"`. @@ -109,6 +109,7 @@ The mechanic: - **Lifecycle suffix in PR titles** (`... wip`, `... draft`, `... scaffolding`). The title outlives the state that named it. The body and GitHub's chip carry lifecycle; the title doesn't need to. - **Mechanic-first titles** (`... move the check above the lookup`, `... reorder the gates`, `... extract the handler`). They describe the code motion, which is the one thing the diff already shows. Lead with the effect or the cause (§PR title). +- **Change lines that retell the diff** (`The handler reads the timeout from the config`, `The sync loop re-queues each entry every 10 minutes`). The title's mechanic failure, one level down: each line names a component and what it does, and the reader still cannot tell what they will see differently. Write each line as the difference a user or an operator will notice, and what it replaces (the template's guidance for `## What lands here` or `## Changes`). - **`Challenges` as the body's overflow section.** Consequences, tradeoffs, follow-up work, and the history of review rounds all get filed there because the heading is sitting in the template. Each has a home: the Description's third part, `Related`, or the commits. The section earns its place only when the diff hides a system fact a reviewer needs — otherwise the heading gets deleted. - **Flipping ready with the draft body unchanged.** Different shape, different audience. Rewrite from the ready template. - **Marking ready before the Testing section is filled in.** That section is what gives the reviewer confidence the PR is shippable; leaving it blank silently drops the claim. diff --git a/skills/opening-a-pull-request/templates/pull-request-draft.md b/skills/opening-a-pull-request/templates/pull-request-draft.md index 4bd8dac..0fbee9f 100644 --- a/skills/opening-a-pull-request/templates/pull-request-draft.md +++ b/skills/opening-a-pull-request/templates/pull-request-draft.md @@ -13,7 +13,9 @@ Open with ONE of these as the FIRST line of this section, depending on what shou - `Towards #` — the PR contributes to the issue but does NOT auto-close it; the issue stays open. Used for sub-PRs into a feature branch and for any other "in progress on this, not finishing it" case. Omit the line entirely if there is no tracking issue. -Then follow with 1-3 sentences forecasting the changes this PR will introduce. Human-readable; treat it as the early-visibility surface for reviewers who might want to flag direction issues now rather than at review time. +Then follow with 1-3 sentences or bullets on the outcomes this PR delivers, or will deliver while the work is still in flight. Treat it as the early-visibility surface for reviewers who might want to flag direction issues now rather than at review time. + +Each outcome is a difference that a user, an operator, or a calling system will notice: what they get with this PR and, when it replaces something they had, what that was. Write it from where they stand. The subject is what they see (a request, a record, a status, an alert), not the component or code path that does the work; the diff and the commits already carry which code changed and where. Fit each sentence to its change rather than one pattern for every line: a fix often reads best from the symptom it ends, a new capability from what it lets them do, a changed default from the old value to the new one. --> ## Related diff --git a/skills/opening-a-pull-request/templates/pull-request-ready.md b/skills/opening-a-pull-request/templates/pull-request-ready.md index 2d6f613..7c7e364 100644 --- a/skills/opening-a-pull-request/templates/pull-request-ready.md +++ b/skills/opening-a-pull-request/templates/pull-request-ready.md @@ -24,7 +24,9 @@ Write it for a dev arriving without context. Lean on Changes (below) for the "wh ## Changes ## Challenges