Skip to content

feat: enable Coder.AcronymPeriods Vale rule - #30783

Closed
nickvigilante wants to merge 5 commits into
mainfrom
vigilante/docs-430-add-coderacronymperiods-vale-rule
Closed

nickvigilante wants to merge 5 commits into
mainfrom
vigilante/docs-430-add-coderacronymperiods-vale-rule

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Depends on #30782.

Adds Coder.AcronymPeriods, a Vale rule that enforces No periods in acronyms.
It flags capitalized acronyms written with periods, such as A.P.I. or U.S..

  • Severity: warning.
  • Scope: docs/** except docs/.style/style-guide/**, with no other exclusions.
  • Baseline: 0 findings, including the generated docs/reference/{api,cli,agent-api} pages, so no cleanup commit.
  • The PR flips the guide footer to enforced, adds the checks-table row, and updates the coverage counts (10 tool-checked, 32 planned) and the tooling paragraph (10 of 87).
  • Known limitation: a version placeholder such as X.Y.Z in plain prose matches as "X.Y.". None exist outside code font today, and the guide asks for code font on placeholders, which Vale skips.

Linear: DOCS-430

Decision log
  • Pattern \b(?:[A-Z]\.){2,}. Google.Periods used {3,}, but U.S. is a two-letter case the guide's Don't example names, so the rule requires two or more pairs.
  • Google rules aren't loaded, so nothing needed turning off.
  • e.g. and i.e. can't match: the rule is case-sensitive and accepts capital letters only. A single initial such as J. Smith can't match either.
  • Existence rule, nonword: true, ignorecase: false, same shape as UnitSpacing.
  • Test fixtures (not committed) with both LF and CRLF endings:
    • Flags: A.P.I., U.S., E.U., and X.Y.Z in prose (reported as X.Y.).
    • Doesn't flag: API, US, e.g., i.e., etc., J. Smith, a.m., p.m., code spans, fenced code.
    • LF and CRLF reported identical findings.
  • Checks: vale docs/ reports 0 Coder.AcronymPeriods findings, go run ./scripts/styleclaims passes, and the pre-commit-light hook (markdownlint, emdash, style-claims) passes.

Generated by Coder Agents on behalf of @nickvigilante.

Add the style rules from the Docs style guide Linear project that the
guide was missing, and fix the guide's own self-violations from the
second ASD-STE100 audit. Each new Vale rule lands in its own PR based
on this one, so every footer for those rules is marked planned.

The Vale doctrine now lets suggestion-level rules land with existing
findings, per Nick's decision on DOCS-450.

Refs DOCS-1282, DOCS-1265
@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-430

@nickvigilante
nickvigilante force-pushed the vigilante/docs-430-add-coderacronymperiods-vale-rule branch from a61c13e to 71d1ff6 Compare October 14, 2026 20:53
Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
Take main's style guide, which already carries the squashed
docs style guide rules, and reapply the AcronymPeriods footer,
checks-table row, and coverage counts on top of main's totals.

Assisted-by: AI
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:29
coder Bot pushed a commit that referenced this pull request Oct 23, 2026
Recreated from #30783 under coder[bot] so it can be reviewed by its requester.
nickvigilante added a commit that referenced this pull request Oct 23, 2026
> [!NOTE]
> Recreated from #30783 under coder[bot] by Superblink, at the request
of @nickvigilante, so he can review and merge it. An AI agent wrote the
original, which was opened from his account. The diff is identical to
#30783, squashed onto current `main`. Superblink reviewed it and ran
Vale over `docs/` before opening this PR (no new warnings or errors).
#30783 should be closed in favor of this one.
> Stack: this is the bottom of a 6-PR stack (#31180 → #31181 → #31182 →
#31183 → #31184 → #31185). Merge them in that order.

Depends on #30782.

Adds `Coder.AcronymPeriods`, a Vale rule that enforces [No periods in
acronyms](https://github.com/coder/coder/blob/main/docs/.style/style-guide/capitalization-and-punctuation.md#no-periods-in-acronyms).
It flags capitalized acronyms written with periods, such as `A.P.I.` or
`U.S.`.

- Severity: `warning`.
- Scope: `docs/**` except `docs/.style/style-guide/**`, with no other
exclusions.
- Baseline: 0 findings, including the generated
`docs/reference/{api,cli,agent-api}` pages, so no cleanup commit.
- The PR flips the guide footer to enforced, adds the checks-table row,
and updates the coverage counts (10 tool-checked, 32 planned) and the
tooling paragraph (10 of 87).
- Known limitation: a version placeholder such as X.Y.Z in plain prose
matches as "X.Y.". None exist outside code font today, and the guide
asks for code font on placeholders, which Vale skips.

Linear: DOCS-430

<details><summary>Decision log</summary>

- Pattern `\b(?:[A-Z]\.){2,}`. Google.Periods used `{3,}`, but `U.S.` is
a two-letter case the guide's Don't example names, so the rule requires
two or more pairs.
- Google rules aren't loaded, so nothing needed turning off.
- `e.g.` and `i.e.` can't match: the rule is case-sensitive and accepts
capital letters only. A single initial such as `J. Smith` can't match
either.
- Existence rule, `nonword: true`, `ignorecase: false`, same shape as
`UnitSpacing`.
- Test fixtures (not committed) with both LF and CRLF endings:
- Flags: `A.P.I.`, `U.S.`, `E.U.`, and `X.Y.Z` in prose (reported as
`X.Y.`).
- Doesn't flag: `API`, `US`, `e.g.`, `i.e.`, `etc.`, `J. Smith`, `a.m.`,
`p.m.`, code spans, fenced code.
  - LF and CRLF reported identical findings.
- Checks: `vale docs/` reports 0 `Coder.AcronymPeriods` findings, `go
run ./scripts/styleclaims` passes, and the pre-commit-light hook
(markdownlint, emdash, style-claims) passes.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*

Created on behalf of @nickvigilante

Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Superseded by #31180, which merged the same change into main as part of the stacked Vale rule PRs. Closing as a duplicate.

Generated by Coder Agents on behalf of @nickvigilante.

@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.

1 participant