Repository navigation
feat(docs): enable Coder.CheckOut Vale rule - #31185
Merged
nickvigilante merged 2 commits intoOct 23, 2026
Merged
nickvigilante merged 2 commits into
nickvigilante merged 2 commits into
Conversation
Contributor
Docs previewCheck 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
Bot
force-pushed
the
superblink/docs-1260-style-guide-drop-check-out-as-a-cross-reference-verb
branch
from
October 23, 2026 08:36
997b8cf to
6f01409
Compare
This was referenced Oct 23, 2026
coder
Bot
changed the base branch from
main
to
superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont
October 23, 2026 08:36
nickvigilante
approved these changes
Oct 23, 2026
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
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
force-pushed
the
superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont
branch
from
October 23, 2026 16:31
f003d51 to
9eb97b8
Compare
nickvigilante
added a commit
that referenced
this pull request
Oct 23, 2026
> [!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](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#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 <details><summary>Decision log</summary> - 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. </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>
Base automatically changed from
superblink/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont
to
main
October 23, 2026 16:36
nickvigilante
force-pushed
the
superblink/docs-1260-style-guide-drop-check-out-as-a-cross-reference-verb
branch
from
October 23, 2026 16:39
6e080df to
70b0a10
Compare
nickvigilante
enabled auto-merge (squash)
October 23, 2026 16:39
nickvigilante
deleted the
superblink/docs-1260-style-guide-drop-check-out-as-a-cross-reference-verb
branch
October 23, 2026 16:44
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Recreated from #30793 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 #30793, squashed onto current
main. Superblink reviewed it and ran Vale overdocs/before opening this PR (no new warnings or errors). #30793 should be closed in favor of this one.Stack: based on #31184 (#31180 → #31181 → #31182 → #31183 → #31184 → #31185). The diff matches #30793 except for the counters in
docs/.style/style-guide/README.md, which build on the PRs below this one.make lint/style-claimspasses at every level.Builds on #30782, which is merged; the branch now merges
main.Adds
Coder.CheckOut, a Vale rule that enforces Refer to or visit, not see or check out.It flips only
Coder.CheckOutin the footer;Coder.SeeAlternativesstays planned.checks out,checked out,checking out) when used to point the reader at a page or site.warning. Scope:docs/**exceptdocs/.style/style-guide/**.docs/ai-coder/agent-firewall/index.md) landed onmainafter the branch was cut.git checkout, "a source checkout"..vale.inichange and no Go source change.Commits:
docs(docs): refer to or visit instead of "check out"feat(docs/.style): enable Coder.CheckOut Vale ruleLinear: DOCS-1260
Decision log
existencerule can't do this. RE2 has no lookahead, so the rule can't say "check out, unless a Git object follows". A token that includes the following words also fails: Vale can't locate a match that spans link text (check out [Dev Containers]renders without the bracket), and it silently drops the finding. Those link-follows cases are the main true positives.extends: script(Tengo, supported by the pinned Vale 3.7.1) withscope: text. It finds each "check out" and reports only those two words. It skips the match when one of the next 3 words is a Git object, or when "and" follows directly.code-marketplaceisn't a Git object.git checkout, "source checkout") or theactions/checkoutaction. The brief mentions "checkout" as a possible verb, but I found no verb use, so I left it out rather than guess.warning, because the rule can't tell the senses apart from text alone.Test cases (fixtures under
/tmp/checkout-test/, not committed), run with LF and CRLF line endings:git checkout main, agit checkout -bfenced block, "Checkout repository" in a list item, "the checkout action", "check outputs", "check output".Known gaps:
Checks:
vale --output=line docs/reports 0Coder.CheckOutfindings.go run ./scripts/styleclaimspasses.Generated by Coder Agents on behalf of @nickvigilante.
Created on behalf of @nickvigilante