Repository navigation
feat(docs): enable Coder.CheckOut Vale rule - #30793
Closed
nickvigilante wants to merge 7 commits into
Closed
nickvigilante wants to merge 7 commits into
nickvigilante wants to merge 7 commits into
Conversation
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.
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.
|
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
marked this pull request as ready for review
October 23, 2026 05:27
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>
Collaborator
Author
|
Superseded by #31185, which merged the same change into Generated by Coder Agents on behalf of @nickvigilante. |
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.
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.