Skip to content

feat(docs): enable Coder.ImperativeNegation Vale rule - #31184

Merged
nickvigilante merged 1 commit into
mainfrom
superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont
Oct 23, 2026
Merged

nickvigilante merged 1 commit into
mainfrom
superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont

Conversation

@coder

@coder coder Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Note

Recreated from #30784 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 #30784, squashed onto current main. Superblink reviewed it and ran Vale over docs/ before opening this PR (no new warnings or errors). #30784 should be closed in favor of this one.
Stack: based on #31183 (#31180 → #31181 → #31182 → #31183 → #31184 → #31185). The diff matches #30784 except for the counters in docs/.style/style-guide/README.md, which build on the PRs below this one. make lint/style-claims passes at every level.

Depends on #30782.

Adds Coder.ImperativeNegation, a Vale rule that flags don't where it opens an imperative and suggests do not.
It enforces Spell out negative instructions.

  • Severity: warning.
  • Scope: docs/** except docs/.style/style-guide/**, which demonstrates the violations on purpose.
  • Baseline: 14 findings in 9 files.
    The cleanup commit fixes all of them, so the rule ships at zero.
    I also fixed one imperative the rule can't see (**Link to their docs**, don't duplicate in content-guidelines.md).
  • Generated reference pages: no findings, so no exclusion.
  • Known gap: an imperative after a bare comma goes unreported.
    Declaratives such as Headings are sentence case, don't lead share that shape.

Linear: DOCS-1262

Decision log
  • Boundary pattern, not a verb list. The rule matches don't (straight or curly apostrophe) only after a paragraph start (\A), a sentence end, a colon, a semicolon, or , and.
  • Comma case. A bare , don't produced false positives (Headings are sentence case, don't lead, events..., such as updates, don't reach clients).
    The rule instead requires a comma that closes an opening If/When/Before/After/Unless/Once/While/Until clause with no other comma in it.
  • \A instead of ^. ^ also matches at a hard-wrapped line start, which flagged usually\ndon't. in managing-templates/index.md.
  • Bold lead-ins (**Note:** Don't) work because Vale strips markup before matching. Code spans are skipped.
  • Table cells and blockquotes are in scope. One table cell and three blockquote or list lines needed cleanup.
  • Don't know where to start? is an elliptical question, so it became Not sure where to start?.
  • Only don't is in scope. can't and won't are rarely imperative.
  • Link uses the GitHub blob form that the existing rules use.
  • Enable commit also updates the checks table, the coverage counts (Voice and tone 0/4 to 1/3, total 9 to 10 tool-checked and 33 to 32 planned), and the "What the tooling checks" counts.

Tests (fixtures in /tmp, not committed), each run with LF and CRLF files:

  • Flagged: paragraph-initial Don't, Run it. Don't, , and don't, curly If..., don’t, ; don't, **Note:** Don't, : don't, list item, table cell, blockquote.
  • Not flagged: You don't need, Tools that don't, Coder won't push, Headings are sentence case, don't lead, If X is blocked, Coder doesn't..., so events, such as updates, don't reach, a hard-wrapped line starting with don't, and `don't` in a code span.
  • vale --output=line docs/: 0 Coder.ImperativeNegation findings outside the style guide.
  • go run ./scripts/styleclaims, make lint/emdash, and the pre-commit hook (markdown, typos, style-claims) pass.

Generated by Coder Agents on behalf of @nickvigilante.

Created on behalf of @nickvigilante

@coder
coder Bot requested a review from nickvigilante as a code owner October 23, 2026 08:30
@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

DOCS-1262

@github-actions github-actions Bot added the community Pull Requests and issues created by the community. label Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 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.

@coder
coder Bot force-pushed the superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont branch from f36d468 to f003d51 Compare October 23, 2026 08:36
coder Bot pushed a commit that referenced this pull request Oct 23, 2026
Recreated from #30793 under coder[bot] so it can be reviewed by its requester. Stacked on #31184.
@coder
coder Bot changed the base branch from main to superblink/docs-182-add-vale-substitution-rule-for-inclusive-language-industry October 23, 2026 08:36
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 added a commit that referenced this pull request Oct 23, 2026
> [!NOTE]
> Recreated from #30786 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
#30786, squashed onto current `main`. Superblink reviewed it and ran
Vale over `docs/` before opening this PR (no new warnings or errors).
#30786 should be closed in favor of this one.
> Stack: based on #31180 (#31180 → #31181 → #31182 → #31183 → #31184 →
#31185). The diff matches #30786 except for the counters in
`docs/.style/style-guide/README.md`, which build on the PRs below this
one. `make lint/style-claims` passes at every level.

Depends on #30782.

Adds `Coder.LGBTQ`, a Vale substitution rule that enforces [Inclusive
LGBTQ
terms](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#inclusive-lgbtq-terms).
It flags outdated terms for sex, gender, and sexual orientation, and
suggests the current term.

- Severity: `warning`.
- Scope: `docs/**` except `docs/.style/style-guide/**`, with no other
exclusions.
- Baseline: 0 findings, including generated pages, so no cleanup commit.
- Adapted from the [alex](https://github.com/errata-ai/alex) `LGBTQ.yml`
list.
alex is MIT licensed (Copyright (c) 2020 errata.ai), and the YAML header
carries the attribution and a list of changes.
- The rule covers every row of the guide table, and none of the guide's
recommended terms trigger it.
- 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.

Linear: DOCS-431

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

- Upstream verified at `errata-ai/alex` `alex/LGBTQ.yml`, MIT license.
`/tmp` draft matched upstream.
- Removed `bi`, because it flags "Power BI".
- Removed `special rights`, because permissions docs could use it as a
plain technical phrase.
- Removed `homo`, because it flags "Homo sapiens".
- Added `a transgender` from the guide table.
It matches only when followed by `is`, `was`, `who`, `and`, `or`, `but`,
`that`, `has`, `had`, `can`, `will`, `would`, or `should`, so `a
transgender person` and `a transgender woman` stay clean.
A noun use followed by punctuation (`Ask a transgender.`) isn't caught.
- `preferred pronouns`, `transgendered`, `gender pronouns`,
`biologically female`, `born a man`, `genetically male`, and
`hermaphrodite` come from upstream.
- `homosexual` is flagged in any use, as upstream does, which is
stricter than the guide's "as a noun".
- Upstream's `|` separator in suggestions became ", ", the form the
other Coder substitution rules use.
- Test fixtures (not committed), LF and CRLF, gave identical results:
- Flags: every guide Don't term, plus the `homosexual` compounds,
`sexual preference`, `sex change`, `bathroom bill`, `transgenders`.
- Doesn't flag: `Power BI`, `bi-directional`, `bi-weekly`,
`homogeneous`, `special rights`, the guide's Do terms, `a transgender
person`, `a transgender woman`, and terms inside code spans and fences.
- Checks: `vale docs/` reports 0 `Coder.LGBTQ` findings, `go run
./scripts/styleclaims` passes, and the pre-commit-light hook 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 added a commit that referenced this pull request Oct 23, 2026
> [!NOTE]
> Recreated from #30792 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
#30792, squashed onto current `main`. Superblink reviewed it and ran
Vale over `docs/` before opening this PR (no new warnings or errors).
#30792 should be closed in favor of this one.
> Stack: based on #31181 (#31180 → #31181 → #31182 → #31183 → #31184 →
#31185). The diff matches #30792 except for the counters in
`docs/.style/style-guide/README.md`, which build on the PRs below this
one. `make lint/style-claims` passes at every level.
> Vale run on current `main`: this rule adds about 655
`suggestion`-level alerts across `docs/`. That matches its documented
`suggestion` severity, and `make lint/prose` never fails on them.

Builds on #30782, which is merged; the branch now merges `main`.

Adds `Coder.AmbiguousWords` at `suggestion` severity.
The rule flags the `ensure` family, `should`, `since`, and `may`, and
suggests the one-meaning replacement from the guide: `make sure`, `must`
or a recommendation, `might` or `can`, and `because` or `after`.
It covers `docs/**` except `docs/.style/style-guide/**` and the
generated `docs/reference/{api,cli}/*.md` pages.

Baseline: 655 findings on current `main`, no cleanup commit.
At branch creation it was 663: 128 `ensure`, 19 `ensures`, 13
`ensuring`, 174 `should`, 58 `since`, and 271 `may`.
The rule ships as a suggestion with its backlog, as
`docs/.style/README.md` allows.
DOCS-1283 tracks the cleanup and the promotion to `warning`.

Known false positives: `since` and `should` can be correct in context,
such as `since` for time ("since version 2.20") and a `should` that
states an expectation.
The rule can't tell, so it stays a suggestion.

Linear: DOCS-1263

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

- **Rule type**: `substitution` with one swap per word form, so the
message names the replacement.
Replacements follow the guide's table: `make sure`, `must, recommend`,
`might, can`, `because, after`.
- **Case**: `ignorecase: false`, with `[Ee]nsure` and `[Ss]hould`
classes, so lowercase `may` and the month `May` stay distinct.
- **`May`**: the pattern `\bMay\b(?!,?\s+\d)` skips the month when a
digit follows ("May 5, 2026", "May 2026", "May, 2026").
Vale compiles lookaheads with a backtracking engine, so the pattern
works.
The sentence-initial `May` in a list item ("May include minor bugs") is
flagged, which is correct.
- **Generated pages**: `.vale.ini` excludes
`docs/reference/{api,cli}/*.md`, as `Coder.UnitSpacing` does.
Those pages hold 168 more findings that come from Go comments and CLI
flag text.
  With the exclusion the baseline is 663, close to the 664 expected.
- **Footer and table**: the section footer names `Coder.AmbiguousWords`
at `suggestion` severity.
The checks table gets a row, and the counts move word choice from 2 to 3
tool-checked.
The formatter widened the Severity column because `suggestion` is longer
than `warning`.

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

- Positive: `Ensure`, `ensures`, `ensured`, `ensuring`, `should`,
`Since`, lowercase `may`, and `May` in "May the build fail", "Then May
is risky", and "May happen".
- Negative: "May 5, 2026", "May 2026", "May, 2026", "May 12", `maybe`,
`mayor`, `shoulder`, `sincere`, and the same words inside code spans.
- A plain `since` in prose is flagged, as intended.

Checks: `make lint/style-claims` passes, the pre-commit hooks pass, and
`vale --output=line docs/` reports 663 `Coder.AmbiguousWords` findings
and no new findings from other rules.

</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
nickvigilante force-pushed the superblink/docs-182-add-vale-substitution-rule-for-inclusive-language-industry branch from 15b5524 to 9e34d23 Compare October 23, 2026 16:21
Base automatically changed from superblink/docs-182-add-vale-substitution-rule-for-inclusive-language-industry to main October 23, 2026 16:26
nickvigilante added a commit that referenced this pull request Oct 23, 2026
> [!NOTE]
> Recreated from #30785 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
#30785, squashed onto current `main`. Superblink reviewed it and ran
Vale over `docs/` before opening this PR (no new warnings or errors).
#30785 should be closed in favor of this one.
> Stack: based on #31182 (#31180 → #31181 → #31182 → #31183 → #31184 →
#31185). The diff matches #30785 except for the counters in
`docs/.style/style-guide/README.md`, which build on the PRs below this
one. `make lint/style-claims` passes at every level.

Depends on #30782.

Adds `Coder.InclusiveLanguage`, a Vale substitution rule that enforces
the [Inclusive-language
substitutions](https://github.com/coder/coder/blob/main/docs/.style/style-guide/accessibility-and-inclusion.md#inclusive-language-substitutions)
table.

- Flags `whitelist`, `blacklist`, `slave`, `master branch`, `master
controller`, `dummy`, `sanity check` and `sanity test`, and
`grandfathered` and its inflections, with the guide's replacement terms.
  It also flags inflections such as `whitelisted` and `slaves`.
- Severity: `warning`.
- Scope: `docs/**` except `docs/.style/style-guide/**` and
`docs/reference/cli/agent-firewall.md`.
- Baseline: 2 findings, both `dummy`.
- `docs/ai-coder/agent-firewall/index.md`: fixed in the cleanup commit
(now "mock DNS server", with the bullet reflowed to one sentence per
line).
  - `docs/reference/cli/agent-firewall.md`: generated page.
The text comes from the `github.com/coder/boundary` dependency's flag
description, so it can't be fixed in this repo.
`.vale.ini` turns the rule off for that page, with a comment, and the PR
changes no generated output.
- After cleanup: 0 findings.
- The PR flips the guide footer to enforced, adds the checks-table row,
updates the coverage counts (10 tool-checked, 32 planned) and the
tooling paragraph, and removes "Inclusive-language substitutions" from
the planned list in `docs/.style/styles/Coder/README.md`.

Linear: DOCS-182

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

- Bare `master` isn't flagged, as the guide footer says. Only `master
branch` and `master controller`, the two senses in the guide table, are.
- Replacement wording follows the guide table, not the issue text:
`slave` becomes "replica, secondary", `sanity check` becomes "smoke
testing, confidence testing, acceptance testing", and `grandfathered`
becomes "legacy, pre-existing, exempt". `blacklist` suggests "blocklist,
denylist" and `dummy` suggests "placeholder, sample, mock".
- Bare `grandfather` isn't flagged, only `grandfather` with an
inflection or `clause`. A `grandfather clock` or a family member would
otherwise match, and a substitution rule's exceptions can't see the
following word.
- `white-list` and `white list` forms are covered, along with `-ed` and
`-ing` forms for white and blacklist.
- Vale skips code spans and fences, so `master` branch names and `dummy`
flags in code font are untouched.
- Test fixtures (not committed), LF and CRLF, gave identical results:
  - Flags: every term above and its inflections.
- Doesn't flag: `master key`, bare `master`, `mastering`, `grandfather
clock`, `sanity` alone, all terms inside code spans and fences, and
every recommended replacement.
- Checks: `vale docs/` reports 0 `Coder.InclusiveLanguage` findings, `go
run ./scripts/styleclaims` passes, and the pre-commit-light hook passes
on both commits.

</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>
Recreated from #30784 under coder[bot] so it can be reviewed by its requester. Stacked on #31183.
@nickvigilante
nickvigilante force-pushed the superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont branch from f003d51 to 9eb97b8 Compare October 23, 2026 16:31
@nickvigilante
nickvigilante enabled auto-merge (squash) October 23, 2026 16:31
@nickvigilante
nickvigilante merged commit 635a1a8 into main Oct 23, 2026
30 checks passed
@nickvigilante
nickvigilante deleted the superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont branch October 23, 2026 16:36
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 23, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant