Skip to content

feat: enable Coder.USSpelling Vale rule - #30790

Merged
nickvigilante merged 2 commits into
mainfrom
vigilante/docs-1280-add-coderusspelling-vale-rule
Oct 24, 2026
Merged

nickvigilante merged 2 commits into
mainfrom
vigilante/docs-1280-add-coderusspelling-vale-rule

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Depends on #30782.

Adds Coder.USSpelling at warning severity.
The rule flags an -ise family (organise, initialise, authorisation) and a list of British spellings (behaviour, labelled, cancelled, analogue, whilst, and others) and suggests the US form.
It covers docs/** except docs/.style/style-guide/** and the generated docs/reference/{api,cli}/*.md pages.

Baseline: 13 findings before cleanup, 0 after.
The first commit fixes 11 of them: 10 in hand-written pages and 1 in the Prometheus metrics table, which comes from metric help text.
Two findings sit in generated reference pages, which .vale.ini excludes for this rule: the CLI alias favourite and amongst in a Go comment from a vendored dependency (the DERP map schema).
The metric help text comes from querymetrics.go, so the fix lands there and in generated_metrics and prometheus.md.

Known false positive: Vale doesn't skip bold text, so a UI label in bold that keeps British spelling is flagged.
The rule comment and the guide footer say to use a code span for such a label.

Linear: DOCS-1280

Decision log
  • Rule type: substitution, so each message names the US form.
    The -ise family can't name a specific replacement, so it suggests "the -ize form".
  • cancelled: the guide's "Use US spelling" section lists canceled and canceling.
    The rule flags the double-l verb forms and leaves cancellation alone, which Merriam-Webster spells with one l.
  • Exceptions: Vale applies an exception to the matched word, so each is anchored with ^ and $ and case-insensitive.
    The list covers -wise words and stems for advise, advertise, exercise, promise, premise, compromise, surprise, comprise, concise, precise, revise, supervise, televise, devise, improvise, franchise, merchandise, disguise, despise, paradise, cruise, noise, raise, rise, wise, and others, each with the endings e, es, ed, ing, er, and ers.
    The mise tool is excepted by name.
  • Extra British spellings beyond the guide table: other doubled-l verbs (signalled, levelled), metre, litre, fibre, theatre, calibre, offence, pretence, analyse, judgement, acknowledgement, ageing, artefact, sceptic, aluminium, practise, enrol, fulfil, instil, skilful.
    None appears in the corpus today.
  • Generated pages: excluded for docs/reference/{api,cli}/*.md, as Coder.UnitSpacing does.
    Changing the favourite alias would change CLI behavior, and the amongst comment isn't ours to edit.
  • Prometheus doc: edited by hand with matching table padding because go run ./scripts/metricsdocgen already rewrites the whole table on the base branch, independent of this change.

Test cases, run with vale --config against fixtures that are not committed, in LF and CRLF:

  • Positive: organise, initialise, authorise, customisation, authorisation, organisations, Organised, initialising, recogniser, customisable, every explicit list entry, and capitalized forms.
  • Negative: advise, exercise, otherwise, Enterprise, premise, compromise, promise, surprise, precise, concise, expertise, revising, supervising, improvising, raise, noise, cruise, franchise, merchandise, disguise, despise, paradise, appraise, sunrise, arise, liaise, clockwise, cancellation, canceled, mise.
  • Skipped: words in code spans and fenced code blocks, such as cancelled.
  • LF and CRLF results are identical.

Checks: vale --output=line docs/ reports 0 Coder.USSpelling findings, make lint/style-claims passes, and the pre-commit hooks pass on both commits.

Generated by Coder Agents on behalf of @nickvigilante.

@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1280

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1280-add-coderusspelling-vale-rule branch from 6dd43f9 to dda8e6d Compare October 14, 2026 21:00
Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:14

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1280-add-coderusspelling-vale-rule branch from 869b82f to 91ca7af Compare October 24, 2026 03:02
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

The Analyze PR for Documentation Updates Needed (doc-check) job timed out after 40 minutes waiting for its agent chat to finish, so no review was posted. All required checks pass. The same timeout hit several PRs around the same time, so this looks like a doc-check service problem rather than anything in this branch. Re-run the job if you want the doc review before merging.

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1280-add-coderusspelling-vale-rule branch from 91ca7af to 0a9266a Compare October 24, 2026 04:19
@nickvigilante
nickvigilante merged commit 9edb2e3 into main Oct 24, 2026
32 of 34 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-1280-add-coderusspelling-vale-rule branch October 24, 2026 05:18
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 24, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants