Skip to content

feat: enable Coder.InclusiveLanguage Vale rule - #30785

Closed
nickvigilante wants to merge 6 commits into
mainfrom
vigilante/docs-182-add-vale-substitution-rule-for-inclusive-language-industry
Closed

nickvigilante wants to merge 6 commits into
mainfrom
vigilante/docs-182-add-vale-substitution-rule-for-inclusive-language-industry

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

Depends on #30782.

Adds Coder.InclusiveLanguage, a Vale substitution rule that enforces the 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

Decision log
  • 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.

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-182

@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-182-add-vale-substitution-rule-for-inclusive-language-industry branch from 507e31f to 9db01cd 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 InclusiveLanguage footer,
checks-table row, and coverage counts on top of main's totals.
Main had already reflowed the Agent Firewall use_real_dns bullet,
so only the "dummy" to "mock" fix is reapplied there.

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 #30785 under coder[bot] so it can be reviewed by its requester. Stacked on #31182.
nickvigilante added a commit that referenced this pull request Oct 23, 2026
Recreated from #30785 under coder[bot] so it can be reviewed by its requester. Stacked on #31182.
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>
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Superseded by #31183, 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