From 4ae4564c7ac467acef65fdfc297f0af12ffe1db2 Mon Sep 17 00:00:00 2001 From: Dennis Doomen Date: Sun, 26 Jul 2026 09:53:13 +0200 Subject: [PATCH] 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).