Skip to content

feat(docs): enable Coder.CheckOut Vale rule - #30793

Closed
nickvigilante wants to merge 7 commits into
mainfrom
vigilante/docs-1260-style-guide-drop-check-out-as-a-cross-reference-verb
Closed

nickvigilante wants to merge 7 commits into
mainfrom
vigilante/docs-1260-style-guide-drop-check-out-as-a-cross-reference-verb

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

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.CheckOut in the footer; Coder.SeeAlternatives stays planned.

  • Flags "check out" and its inflections (checks out, checked out, checking out) when used to point the reader at a page or site.
  • Severity: warning. Scope: docs/** except docs/.style/style-guide/**.
  • Baseline: 11 findings in 10 pages, 0 after cleanup. One of them (docs/ai-coder/agent-firewall/index.md) landed on main after the branch was cut.
  • Cleanup rewrites each to "refer to" (docs destinations) or "visit" (external destinations).
  • The Git sense is allowed and isn't flagged. Examples: "check out the branch", git checkout, "a source checkout".
  • Generated pages: no findings, so no .vale.ini change and no Go source change.

Commits:

  1. docs(docs): refer to or visit instead of "check out"
  2. feat(docs/.style): enable Coder.CheckOut Vale rule

Linear: DOCS-1260

Decision log
  • Vale's existence rule 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.
  • The rule is therefore extends: script (Tengo, supported by the pinned Vale 3.7.1) with scope: 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.
  • Git objects skipped: branch, repo, repository, code, source, commit, tag, PR, pull request, fork, clone, worktree, file, revision, ref, master, main, trunk, submodule, sha, changes, release, version, folder, directory, dotfiles. A hyphenated name such as code-marketplace isn't a Git object.
  • The one-word "checkout" is never flagged. In this corpus it's a Git noun or command (git checkout, "source checkout") or the actions/checkout action. 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:

  • Flagged (8 each): link follows ("Check out [Dev Containers integration]"), "check out our [module registry]", "check out HashiCorp's [Getting Started Guides]", "Checking out the [Quickstart]", "checked out" in a blockquote, "Checks out" in a list item, a heading ("Check out more"), a hard-wrapped "check out the\n[envbox docs]".
  • Not flagged (0 each): "check out the branch", "the repository", "the code", "a commit", "the tag", "the PR", "the pull request", "check out and install a dotfiles repository", "source checkout", "Git checkout", git checkout main, a git checkout -b fenced block, "Checkout repository" in a list item, "the checkout action", "check outputs", "check output".

Known gaps:

  • False negative: a cross-reference that names a Git word right after the verb, such as "check out our code samples".
  • False positive risk: a Git sense with an object the list doesn't name.

Checks:

  • vale --output=line docs/ reports 0 Coder.CheckOut findings.
  • go run ./scripts/styleclaims passes.
  • 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
Replaces 10 uses of "check out" as a cross-reference verb. The Git sense stays.
Flags "check out" as a cross-reference verb at warning severity, skips the Git sense, and flips the style guide footer from planned to enforced.
@nickvigilante nickvigilante changed the title feat(docs/.style): enable Coder.CheckOut Vale rule feat(docs): enable Coder.CheckOut Vale rule Oct 14, 2026
@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1260

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
…-as-a-cross-reference-verb

Take main's style guide and reflowed pages, which carry the squash-merged base commits from #30782, then reapply this branch's check out rewrites and the Coder.CheckOut row and counts. Also rewrite a check out cross-reference that landed on main in docs/ai-coder/agent-firewall/index.md.

Assisted-by: AI
Run pnpm run format-docs so markdown-table-formatter aligns the table after the merge added a row.

Assisted-by: AI
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:27
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.
nickvigilante added 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.
nickvigilante added a commit that referenced this pull request Oct 23, 2026
> [!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 over `docs/` 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-claims` passes 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](https://github.com/coder/coder/blob/main/docs/.style/style-guide/word-choice.md#refer-to-or-visit-not-see-or-check-out).
It flips only `Coder.CheckOut` in the footer; `Coder.SeeAlternatives`
stays planned.

- Flags "check out" and its inflections (`checks out`, `checked out`,
`checking out`) when used to point the reader at a page or site.
- Severity: `warning`. Scope: `docs/**` except
`docs/.style/style-guide/**`.
- Baseline: 11 findings in 10 pages, 0 after cleanup. One of them
(`docs/ai-coder/agent-firewall/index.md`) landed on `main` after the
branch was cut.
- Cleanup rewrites each to "refer to" (docs destinations) or "visit"
(external destinations).
- The Git sense is allowed and isn't flagged. Examples: "check out the
branch", `git checkout`, "a source checkout".
- Generated pages: no findings, so no `.vale.ini` change and no Go
source change.

Commits:

1. `docs(docs): refer to or visit instead of "check out"`
2. `feat(docs/.style): enable Coder.CheckOut Vale rule`

Linear: DOCS-1260

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

- Vale's `existence` rule 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.
- The rule is therefore `extends: script` (Tengo, supported by the
pinned Vale 3.7.1) with `scope: 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.
- Git objects skipped: branch, repo, repository, code, source, commit,
tag, PR, pull request, fork, clone, worktree, file, revision, ref,
master, main, trunk, submodule, sha, changes, release, version, folder,
directory, dotfiles. A hyphenated name such as `code-marketplace` isn't
a Git object.
- The one-word "checkout" is never flagged. In this corpus it's a Git
noun or command (`git checkout`, "source checkout") or the
`actions/checkout` action. 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:

- Flagged (8 each): link follows ("Check out [Dev Containers
integration]"), "check out our [module registry]", "check out
HashiCorp's [Getting Started Guides]", "Checking out the [Quickstart]",
"checked out" in a blockquote, "Checks out" in a list item, a heading
("Check out more"), a hard-wrapped "check out the\n[envbox docs]".
- Not flagged (0 each): "check out the branch", "the repository", "the
code", "a commit", "the tag", "the PR", "the pull request", "check out
and install a dotfiles repository", "source checkout", "Git checkout",
`git checkout main`, a `git checkout -b` fenced block, "Checkout
repository" in a list item, "the checkout action", "check outputs",
"check output".

Known gaps:

- False negative: a cross-reference that names a Git word right after
the verb, such as "check out our code samples".
- False positive risk: a Git sense with an object the list doesn't name.

Checks:

- `vale --output=line docs/` reports 0 `Coder.CheckOut` findings.
- `go run ./scripts/styleclaims` passes.
- 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>

@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

Copy link
Copy Markdown
Collaborator Author

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

2 participants