Skip to content

Commit 8d8b0a3

Browse files
leggetterclaude
andcommitted
docs: write down the spelling convention
Asked whether the release notes are in American English. They are not — they are British, which matches the codebase (behaviour 19 to behavior 5, honoured 10 to 0). But nothing said so, and the published notes show it: v2.6.0 uses "behavior" and "honoured" in the same document. AGENTS.md § 6 now states it, with the part that actually causes mistakes: identifiers keep their real spelling. --color, NO_COLOR and ansi.Color() are literals a reader types, and an API field named behavior stays behavior when quoted. One sentence can carry both spellings and be correct. The release-notes voice guide points at it rather than restating it, since this applies to help text and docs too. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 68f1f14 commit 8d8b0a3

2 files changed

Lines changed: 22 additions & 0 deletions

File tree

‎.agents/skills/hookdeck-cli-release/references/release-notes-voice.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,12 @@ gh release view v2.6.0 --json body -q .body | wc -w # ~1438
3535
wc -w <your-draft.md>
3636
```
3737

38+
## Spelling
39+
40+
British in prose, literal for identifiers — `--color` stays `--color` while the colour it prints is
41+
spelled the British way. The rule and the reasoning are in **AGENTS.md § 6**; recent notes are
42+
inconsistent because it was not written down until now.
43+
3844
## Structure
3945

4046
`## Summary`, then only the sections with content: `New features`, `Fixes`,

‎AGENTS.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -334,6 +334,22 @@ go run . login --help
334334
335335
## 6. Documentation Standards
336336
337+
### Spelling: British prose, literal identifiers
338+
339+
Prose uses **British** spelling — `behaviour`, `honoured`, `recognise`, `colour`, `initialise`.
340+
That is what the codebase already does (behaviour 19 to behavior 5, honoured 10 to 0) and what the
341+
release notes lean towards, though they are inconsistent because this was never written down:
342+
v2.6.0 used "behavior" and "honoured" in the same document.
343+
344+
**Identifiers keep their real spelling**, always. A flag, environment variable, API field, struct
345+
tag or library symbol is a literal, not prose:
346+
347+
- `--color`, `NO_COLOR`, `ansi.Color()` — never `--colour`
348+
- an API field named `behavior` stays `behavior` when quoted as a field
349+
350+
So a sentence can legitimately carry both: "`--color off` also suppresses the colour in piped
351+
output." Check whether the word is something the reader types before you change its spelling.
352+
337353
### Command help text (Short and Long)
338354
339355
Use the shared helpers in **`pkg/cmd/helptext.go`** for resource commands so Short and the common part of Long are defined once and stay consistent across sources, connections, and any future resources.

0 commit comments

Comments
 (0)