PR rules: a title has to make sense to someone who never saw the chat (#11202)

* PR rules: a title has to make sense to someone who never saw the chat

Agents write PR titles from inside their own context, or copy the issue's title, so a maintainer reading the list can't tell what a PR does. AGENTS.md, the contributing skill, CONTRIBUTING.md and the PR template now say who a title is for and show an unclear and a clear one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K14jA88xLsBfMkWo4Da5uh

* PR rules: write PR text in plain, literal English, and use a clearer example title

The first example still said "that window", the kind of pointing word the rule bans. The new rule takes the useful parts of Simplified Technical English without its approved-word list, which doesn't fit CAD terms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01K14jA88xLsBfMkWo4Da5uh

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bherbruck
2026-11-02 16:02:56 +00:00
committed by GitHub
parent c7547eb3a8
commit 927a5c3733
4 changed files with 28 additions and 0 deletions
+2
View File
@@ -1,3 +1,5 @@
<!-- Title: which part of the app changes and what a user now sees or can do, clear to someone who hasn't seen your chat, the issue or the code. -->
## Change
Start with what this is, in plain words someone new to the project would understand: what it does and who it's for. Don't assume anyone knows the name of your tool, project or feature. Then describe the problem and resulting behavior. Link the issue when applicable.
+1
View File
@@ -22,6 +22,7 @@ Work: ROADMAP.md, "Where help is wanted most" in CONTRIBUTING.md, issues labelle
- A changed default keeps the old behaviour behind a preference and fills the PR's `Changes a default:` line, and no second PR for an issue a lower-numbered one closes: `pr-checks.yml`.
- A regression test goes in the area's existing test file, never a per-bug file (#3226).
- Look at open PRs first, claim with a draft PR (lowest number wins), one topic per PR, never force-push `main`, no pushes just to catch up with `main`: `skills/solidcraft-contributing/SKILL.md`.
- A PR's title and first sentence make sense to someone who never saw your chat or the issue: `skills/solidcraft-contributing/SKILL.md`.
- Show observable changes with real screenshots or a recording, captured yourself.
- Run `cargo xtask ci` before every commit, without switching branches while it runs. `cargo xtask skills` keeps this file and `skills/` honest.
+9
View File
@@ -339,6 +339,15 @@ and a fresh CI run:
PRs in groups by area, so PRs that touch the same code meet a conflict at most once.
4. Reference the issue (`Fixes #12`). In the PR, say what you tested and how. For geometry work, include the measured numbers (and
the expected ones).
5. Write the PR title and first sentence for someone who hasn't seen your chat, the issue or the
code. Maintainers pick what to review from the title, and it becomes the commit on `main`. Say
which part of the app changes and what a user now sees or can do, and name things rather than
leaning on "there", "it" or "this".
- Unclear: `Send to Slicer: pick one print face per body there, and show print faces only while it is open`
- Clear: `3D printing: choose the face each body rests on in the Send to Slicer window, not the face menu`
Use plain, literal English in PR text: one idea per sentence, active voice, and one word for one
thing. This helps everyone, including readers whose first language isn't English.
Commenting `/claim` assigns you, adds the `in progress` label, and replies with its automatic cleanup
deadline. It frees a claim with no linked PR after 72 hours, or a claim with a PR after 14 days
+16
View File
@@ -24,6 +24,22 @@ not modelling a part through MCP.
draft PR titled `<summary> (#N)`. The lowest-numbered open PR for an issue wins; close yours if it
lost. The bot assigns you and labels the issue `in progress`. Do not claim by editing files; comment
`/claim` only to stake a claim before you have a branch.
- **Write the title and first sentence for a reader who has seen nothing else.** Not your chat, not the
issue, not the code. Maintainers pick what to review from the title, and it becomes the commit on
`main`. Say which part of the app changes and what a user now sees or can do, in everyday words. Don't
paste the issue's title unless it passes this too. Before opening the PR, and again before marking it
ready, read both with everything else closed: if "there", "it", "this" or "that" has nothing to point
at, or a term only makes sense after reading the diff, rewrite it. Keep the terms a user sees in the
app and explain the others.
- Unclear: `Send to Slicer: pick one print face per body there, and show print faces only while it is open`
- Clear: `3D printing: choose the face each body rests on in the Send to Slicer window, not the face menu`
- **Write PR text in plain, literal English.** This follows the spirit of Simplified Technical English,
not its approved-word list. Keep the names a user sees in the app, even if they aren't everyday words.
- One idea per sentence, and about 20 words at most.
- Use active voice: "The view tints the face", not "The face is tinted".
- Use one word for one thing, and don't switch to a synonym partway through.
- Repeat the noun when "it" or "this" could be unclear.
- Don't stack nouns: "the option for picking in the face menu", not "face menu picking option".
- **Push daily.** A draft with no pushes for 72 hours may be taken over: comment first, then open your
own claim (you may start from its branch). The bot's automatic cleanup deadlines in CONTRIBUTING.md
are separate.