Skip to content

Add a glossary of repo jargon to conventions.md #543

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

Closed
dennisdoomen wants to merge 1 commit into from
Closed

Add a glossary of repo jargon to conventions.md #543

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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