Skip to content

Use American English throughout - #25

Merged
zmofei merged 2 commits into
mainfrom
american-english
Sep 16, 2026
Merged

zmofei merged 2 commits into
mainfrom
american-english

Conversation

@mattpodwysocki

@mattpodwysocki mattpodwysocki commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Spellings were mixed across 28 files — mostly my own writing. honoured, behaviour, recognise, serialise, neighbour, licence, centred, whilst, sanitised, defence and friends.

Nearly all of it is comments and doc prose, but some is text a user actually sees, so this isn't purely cosmetic:

Where Was
auth status unrecognised prefix
a bad token Mapbox does not recognise the token it would be given.
completion, tilesets-cli (×2) Warning: `--output` is not honoured by …
a result that won't serialize {"code":"error","message":"unserialisable error"}

Second commit: the convention is now a test

There's no AGENTS.md in this repo, so the instruction went into CONTRIBUTING.md — and specifically into the section that already lists four rules "the compiler holds rather than a reviewer". A spelling nobody checks is exactly what drifts across 27 files before anyone notices, so prose_is_american_english in tests/source_guards.rs holds it instead.

It earned its place immediately. My sweep used a word-boundary regex; the guard found 16 lines it had missed, every one real:

  • eprint_labelled, labelled_lines and five test names around them — identifiers, where \b never matches inside labelled_lines
  • mislabelled, Serialising — the British word as a prefix or suffix of a longer one
  • "unserialisable error", which the CLI prints
  • Honouring at the start of a sentence

That's the argument for the test over the instruction, made by the test on its first run.

Two deliberate exemptions. Fenced code blocks, because sample output and captured API responses are quoted rather than written — docs/commands.md is full of both, and a British place name in a geocoding result is not a misspelling; rewriting it would make the doc misquote the API. And cancelled, for the reason below.

Also: the table of spellings to avoid is itself a list of spellings to avoid, so the check skips a line that is nothing but two quoted strings and a comma — narrow enough to excuse a data row and not a sentence.

Verified both ways, not just by a green run:

# British spelling in prose
src/output.rs:88: recognis -> recogniz          → FAILED

# the same word inside a fenced block
test result: ok. 1 passed

cancelled is deliberately left alone

CliError::new("cancelled", "Cancelled — nothing was sent.")

That string is the machine-readable code in the JSON error contract, documented in docs/commands.md's status table and asserted in tests/non_interactive.rs, so anyone scripting against us may be matching on it. Renaming it is a breaking change, not a spelling fix. My recommendation is to do it, before 1.0 while it's cheap, but as its own PR with its own changelog entry — happy to open that.

Scope

  • openapi/ and custom-openapi/ excluded, and the guard excludes them too: their descriptions reach users as help text, but the words are the API teams', mirrored from upstream, and an edit wouldn't survive a regenerate. Both are clean today.
  • No changelog entry. Error message text isn't one of the promises CONTRIBUTING.md lists — command names, flags, the two output modes and the exit codes are. (This also keeps the PR off the same ## Unreleased lines as Document installing without the install script #26.)

597 tests, cargo fmt --check and cargo clippy --locked --all-targets clean.

Mixed spellings across 28 files, mostly mine: `honoured`, `behaviour`,
`recognise`, `serialise`, `neighbour`, `licence`, `centred`, `whilst`,
`sanitised`, `defence` and friends. 91 lines, comments and doc prose plus a
handful of strings the user actually sees:

- `auth status` said "unrecognised prefix"
- a bad token said "Mapbox does not recognise the token it would be given."
- three warnings said "`--output` is not honoured by ..."

The `cancelled` error code is deliberately left alone. It is the
machine-readable `code` in the JSON error contract, documented in
docs/commands.md and asserted in tests/non_interactive.rs, so renaming it is
a breaking change rather than a spelling fix. Worth doing before 1.0, but as
its own decision with its own changelog entry.

No behaviour change otherwise, and nothing generated was touched: openapi/ and
internal/ are excluded, docs/commands.md's sample output is untouched, and
every edited line sits outside a code fence.
@mattpodwysocki
mattpodwysocki requested a review from a team as a code owner September 15, 2026 19:08
CONTRIBUTING.md now says to write American English, and
`prose_is_american_english` in tests/source_guards.rs holds it. The argument
is the one that file's neighbours already make: the section this lands in
lists four rules the compiler holds "rather than a reviewer", and a spelling
nobody is checking is exactly the kind of thing that drifts across 27 files
before anyone notices.

It earned its place immediately. The sweep in the previous commit used a
word-boundary regex, and this guard found sixteen lines it had missed, all
of them real:

- `eprint_labelled` and `labelled_lines` in output.rs, plus five test names
  around them — identifiers, where `\b` does not match inside
  `labelled_lines`
- `mislabelled` and `Serialising`, where the British word is a prefix or
  suffix of a longer one
- `"unserialisable error"`, which is a message the CLI prints
- `Honouring` at the start of a sentence

Two things are skipped deliberately. Fenced code blocks, because sample
output and captured API responses are quoted rather than written and
rewriting a word inside one would make the document misquote its source —
docs/commands.md is full of both, and a British place name in a geocoding
result is not a misspelling. And `cancelled`, which is a compatibility
promise rather than a spelling, with the reason on the constant.

The table of spellings to avoid is itself a list of spellings to avoid, so
the check skips a line that is nothing but two quoted strings and a comma.
Narrow enough to excuse a data row and not a sentence.

Verified both ways rather than trusting a green run: a British spelling in
prose fails, naming `src/output.rs:88`, and the same word inside a fenced
block passes.

No changelog entry. Error *message* text is not one of the promises
CONTRIBUTING.md lists — command names, flags, the output modes and the exit
codes are.

597 tests, fmt and clippy clean.
@zmofei

zmofei commented Sep 16, 2026

Copy link
Copy Markdown
Member

@mattpodwysocki I’ll merge this one and rebase the other PRs onto main, since I noticed some duplicate changes across the PRs.

@zmofei
zmofei merged commit ce4baf4 into main Sep 16, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants