From 6ffb99ab1f9b27698eea667ec57ca8b99410dbd4 Mon Sep 17 00:00:00 2001 From: Dennis Doomen Date: Sun, 26 Jul 2026 09:53:56 +0200 Subject: [PATCH 1/2] Make the non-native-English PR/issue guidance concrete The existing rule was one abstract line and easy to ignore in practice (see PR #528's description). Break it into checkable rules -- one idea per sentence, no idioms, define jargon on first use, gloss cross-references -- and add two anti-pattern examples pulled from a real PR description. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/agents/issue-and-pr-style.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/agents/issue-and-pr-style.md b/docs/agents/issue-and-pr-style.md index c360b8990..f1a2c3474 100644 --- a/docs/agents/issue-and-pr-style.md +++ b/docs/agents/issue-and-pr-style.md @@ -19,7 +19,23 @@ does not constrain an agent running `gh issue create`). marketing tone ("elegant", "robust", "seamlessly"), no emoji section headers. - **Write for non-native English readers.** Plain words over idiom, short sentences, no slang or cultural references — many contributors read English as - a second language. Clarity beats cleverness. + a second language. Clarity beats cleverness. Concretely: + - **One idea per sentence.** Don't stack clauses with em-dashes or semicolons + ("This doesn't do X — that stands — it does Y, and gives Z a path off W"). + Split into separate sentences or bullets. + - **No idioms or figurative language.** "Blast radius", "shrinks the gap", + "grace period", "ceiling", "shallow by design" don't translate. Say what you + mean literally: "affects fewer consumers", "closes the gap", "temporary + fallback", "limit", "handles the common case only". + - **Define repo jargon on first use, or link it.** Terms like "shim", + "sentinel", "canonical type" are fine once explained — link to the + [glossary in conventions.md](conventions.md#glossary-of-repo-jargon) or a + one-clause gloss the first time a PR uses them, don't assume the reader + already knows the vocabulary. + - **Spell out cross-references.** Don't lean on `#257`/`#253` alone — add a + 3–5 word gloss of what each one did ("#257, the ProjectModel rename"). + - **Prefer short, common words.** "use" over "leverage", "keep" over + "preserve", "shows" over "surfaces", "fixes" over "remediates". - **Bullets over prose** for anything enumerable. - **Link, don't recap.** Reference issues (`#123`), PRs, docs, and code (`path/to/file.cs:42`) instead of pasting them. @@ -93,3 +109,5 @@ Closes # | Three paragraphs restating the title | One line, then bullets | | Pasting the full stack trace inline | Link to the run / collapse in `
` | | "As part of this work, I also…" | A second bullet, or a second PR | +| "This doesn't reclassify #257 — that break stands — it shrinks the blast radius for consumers upgrading from 11.0.1–11.0.12" | "#257 (the ProjectModel rename) is still breaking. This PR only makes upgrading past it easier for 11.0.1–11.0.12 users." | +| "Deliberately shallow… same ceiling as the generated shim" | "This only covers the common case. For everything else, use `fallout-migrate`." | From 337034b36bad7f8e15a917f9b07fb9fe1579e9b9 Mon Sep 17 00:00:00 2001 From: Dennis Doomen Date: Sun, 26 Jul 2026 09:53:13 +0200 Subject: [PATCH 2/2] Add a glossary of repo jargon to conventions.md Terms like shim, sentinel, and canonical type show up often in PRs and issues but are never defined anywhere, making descriptions hard to follow for non-native English readers. Add a short glossary and link to it from issue-and-pr-style.md's non-native-English guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/agents/conventions.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/agents/conventions.md b/docs/agents/conventions.md index 091f23fc8..d0dd9cc1b 100644 --- a/docs/agents/conventions.md +++ b/docs/agents/conventions.md @@ -27,6 +27,23 @@ Applies to AI tools and humans. Many readers are non-native English speakers — Covers GitHub issues, PR titles/bodies/comments, and commit messages. +## Glossary of repo jargon + +Terms that come up often in issues, PRs, and code comments. Link here (or gloss +the term in one clause) the first time a PR or issue uses one of these — +per [issue-and-pr-style.md](issue-and-pr-style.md), don't assume the reader +already knows the vocabulary. + +| Term | Meaning | +| --- | --- | +| **Shim** | A small compatibility layer that makes old code keep compiling/working against a new API, without being the real implementation. | +| **Transition shim** | A shim meant to be temporary — it exists only to ease an upgrade and is expected to be removed later. | +| **Sentinel** (e.g. "consumer sentinel") | A small test project whose only job is to fail the build if something regresses — an early-warning check, not a feature. | +| **Canonical type / namespace** | The current, "real" location of a type — as opposed to an old namespace kept alive only by a shim. | +| **Ceiling** (of a shim/fix) | The limit of what a shim or fix covers — what it does *not* handle, so the reader knows when to reach for something else. | +| **Shallow (by design)** | The change intentionally covers only the common case, not every possible scenario. | +| **Blast radius** | How many consumers/how much code is affected by a change. | + ## `[Experimental]` for opt-in unstable APIs Per [ADR-0004 §5](../adr/0004-calendar-versioning-and-dual-pace-channels.md) (channel ladder amended by [ADR-0008](../adr/0008-collapse-experimental-into-main.md)), public APIs that aren't ready to commit to a stability guarantee are marked with [`System.Diagnostics.CodeAnalysis.ExperimentalAttribute`](https://learn.microsoft.com/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute) instead of being held back or shipped silently. The attribute ships in the .NET 8+ BCL — **no package reference needed** (the repo targets .NET 10).