Skip to content

Make the non-native-English PR/issue guidance concrete #544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dennisdoomen merged 2 commits into from
Jul 26, 2026
Merged

Make the non-native-English PR/issue guidance concrete #544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6ffb99a
Make the non-native-English PR/issue guidance concrete
dennisdoomen Jul 26, 2026
337034b
Add a glossary of repo jargon to conventions.md
dennisdoomen Jul 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/agents/conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
20 changes: 19 additions & 1 deletion docs/agents/issue-and-pr-style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -93,3 +109,5 @@ Closes #<issue>
| Three paragraphs restating the title | One line, then bullets |
| Pasting the full stack trace inline | Link to the run / collapse in `<details>` |
| "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`." |