feat(docs): enable Coder.CheckOut Vale rule (#31185)
> [!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>
This commit is contained in:
1 parent
a3876a3634
commit
78aa570078
13 files changed
+63
-17
No files matched your search
@@ -23,8 +23,8 @@ The doctrine for adding Vale rules lives in the [Vale doctrine README](../README
|
||||
|
||||
A clean `make lint/prose` run is not evidence that a page follows this guide.
|
||||
The guide documents 88 rules.
|
||||
Automated tooling checks 16 of them, and 1 of those 16 doesn't run on published pages.
|
||||
The other 72 are yours to apply by reading, 73 on published pages, where the one-sentence-per-line rule is off.
|
||||
Automated tooling checks 17 of them, and 1 of those 17 doesn't run on published pages.
|
||||
The other 71 are yours to apply by reading, 72 on published pages, where the one-sentence-per-line rule is off.
|
||||
|
||||
Open the section that matches what you're writing and work through it.
|
||||
The linters catch a narrow band of mechanical errors; they can't tell you that a page serves 2 audiences, buries a required step in a `NOTE`, or wraps every paragraph at 80 columns.
|
||||
@@ -42,6 +42,7 @@ The linters catch a narrow band of mechanical errors; they can't tell you that a
|
||||
| `Coder.SelectClick` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | `click` and its inflections |
|
||||
| `Coder.OneSentencePerLine` | Vale | `warning` | `docs/.style/*.md` and `docs/.style/styles/Coder/*.md` only | Sentence boundaries mid-line, on contributor docs only |
|
||||
| `Coder.UnitSpacing` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` and `docs/admin/integrations/prometheus.md` and `docs/admin/setup/configuration-reference.md` and `docs/reference/{api,cli}/*.md` | A regular space, or no space, between a number and its unit |
|
||||
| `Coder.CheckOut` | Vale | `warning` | `docs/**` except `docs/.style/style-guide/**` | `check out` as a cross-reference verb, not the Git sense |
|
||||
| `Coder.AmbiguousWords` | Vale | `suggestion` | `docs/**` except `docs/.style/style-guide/**` and `docs/reference/{api,cli}/*.md` | `ensure`, `should`, `since`, and `may` (not the month `May`) |
|
||||
| `MD001`, `MD025`, `MD040`, `MD045` | markdownlint | `error` | All Markdown | Heading increments, single H1, fence language, missing alt text |
|
||||
| `scripts/check_emdash.sh` | `make lint/emdash` | `error` | Repository | Em-dash, en-dash, and `--` as punctuation |
|
||||
@@ -63,12 +64,12 @@ The markdownlint, emdash, docs HTML, and docs-manifest checks do fail the build.
|
||||
| [Audience and scope](./audience-and-scope.md) | 6 | 0 | 0 | 6 |
|
||||
| [Voice and tone](./voice-and-tone.md) | 12 | 1 | 3 | 8 |
|
||||
| [Procedural writing](./procedural-writing.md) | 6 | 0 | 1 | 5 |
|
||||
| [Word choice](./word-choice.md) | 20 | 3 | 11 | 6 |
|
||||
| [Word choice](./word-choice.md) | 20 | 4 | 10 | 6 |
|
||||
| [Accessibility and inclusion](./accessibility-and-inclusion.md) | 14 | 5 | 3 | 6 |
|
||||
| [Capitalization and punctuation](./capitalization-and-punctuation.md) | 12 | 3 | 7 | 2 |
|
||||
| [Formatting](./formatting.md) | 13 | 3 | 0 | 10 |
|
||||
| [Numbers, units, and dates](./numbers-units-and-dates.md) | 5 | 1 | 4 | 0 |
|
||||
| **Total** | 88 | 16 | 29 | 43 |
|
||||
| **Total** | 88 | 17 | 28 | 43 |
|
||||
|
||||
Every column counts rule sections, not linter rule names.
|
||||
A rule section is a heading that carries an enforcement footer, the italic line that names the section's enforcement status.
|
||||
@@ -95,7 +96,7 @@ Classify a counted section from its footer, in this order:
|
||||
A section that names several checks still counts once.
|
||||
3. Anything else: the section is planned.
|
||||
|
||||
So the 14 rows in the table above name 17 checks, because the markdownlint row bundles 4, and those 17 checks cover 16 sections: each check counts under the section that owns it rather than under every section that mentions it.
|
||||
So the 15 rows in the table above name 18 checks, because the markdownlint row bundles 4, and those 18 checks cover 17 sections: each check counts under the section that owns it rather than under every section that mentions it.
|
||||
|
||||
A rule marked `(planned)` in a section footer names the rule that would enforce it if it existed.
|
||||
It isn't running today.
|
||||
|
||||
@@ -419,7 +419,8 @@ In a list of outcomes, "learn why the build fails" or "find out why the build fa
|
||||
>
|
||||
> Add a Ruby option, then see why the option alone doesn't install the toolchain.
|
||||
|
||||
*Enforced by `Coder.SeeAlternatives` (planned) and `Coder.CheckOut` (planned).*
|
||||
*Enforced by `Coder.SeeAlternatives` (planned) and `Coder.CheckOut` (`warning`).
|
||||
The rule leaves the Git sense alone: it skips a "check out" followed within 3 words by a Git object such as a branch, repository, commit, tag, or pull request, or by "and".*
|
||||
|
||||
## Learn more, not Next steps
|
||||
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
# Coder.CheckOut - use "refer to" or "visit" instead of "check out" when the
|
||||
# prose points the reader at a page, section, or site.
|
||||
# Refer to word-choice.md#refer-to-or-visit-not-see-or-check-out for the rule.
|
||||
#
|
||||
# The Git sense of "check out" is allowed ("check out the branch", "check out
|
||||
# a commit"), and so is the noun "checkout" ("a source checkout"), which this
|
||||
# rule never matches. A match that spans link text can't be located in the
|
||||
# source, so the rule is a script: it finds each "check out" and reports only
|
||||
# those two words, after skipping a Git object in the next 3 words (a
|
||||
# hyphenated name such as `code-marketplace` isn't one) or an "and" right after
|
||||
# the verb ("check out and install a dotfiles repository").
|
||||
#
|
||||
# Level: warning. A cross-reference that names a Git word right after the verb
|
||||
# is skipped, and a Git sense with an object the list below doesn't name is
|
||||
# flagged, because the rule can't tell the two senses apart from text alone.
|
||||
extends: script
|
||||
message: "Use 'refer to' or 'visit' instead of '%s' for a cross-reference. Refer to word-choice.md#refer-to-or-visit-not-see-or-check-out."
|
||||
link: https://github.com/coder/coder/blob/main/docs/.style/style-guide/word-choice.md#refer-to-or-visit-not-see-or-check-out
|
||||
level: warning
|
||||
scope: text
|
||||
script: |
|
||||
text := import("text")
|
||||
matches := []
|
||||
|
||||
verb := `(?i)\bcheck(?:s|ed|ing)?[ \t\r\n]+out\b`
|
||||
gitWord := `(?i)(?:^|[^\w-])(?:branch(?:es)?|repos?|repositor(?:y|ies)|code|source|commits?|tags?|prs?|pull|requests?|forks?|clones?|worktrees?|files?|revisions?|refs?|master|main|trunk|submodules?|sha|changes|release|version|folder|directory|dotfiles)(?:$|[^\w-])`
|
||||
andNext := `(?i)^[ \t\r\n]+and\b`
|
||||
|
||||
found := text.re_find(verb, scope, -1)
|
||||
if found != undefined {
|
||||
for group in found {
|
||||
m := group[0]
|
||||
rest := scope[m.end:]
|
||||
// The 3 words after the verb are the window that can name a Git object.
|
||||
window := text.re_find(`^(?:[ \t\r\n]+[\w'’-]+){0,3}`, rest, 1)
|
||||
ctx := ""
|
||||
if window != undefined {
|
||||
ctx = window[0][0].text
|
||||
}
|
||||
if !text.re_match(gitWord, ctx) && !text.re_match(andNext, rest) {
|
||||
matches = append(matches, {begin: m.begin, end: m.end, text: m.text})
|
||||
}
|
||||
}
|
||||
}
|
||||
+2
-2
@@ -7,12 +7,12 @@ title: Administration
|
||||
These guides contain information on managing the Coder control plane and [authoring templates](./templates/index.md).
|
||||
|
||||
First time viewers looking to set up control plane access can start with the [configuration guide](./setup/index.md).
|
||||
If you're a team lead looking to design environments for your developers, check out our [templates guides](./templates/index.md).
|
||||
If you're a team lead looking to design environments for your developers, refer to our [templates guides](./templates/index.md).
|
||||
If you are a developer using Coder, we recommend the [user guides](../user-guides/index.md).
|
||||
|
||||
For automation and scripting workflows, see our [CLI](../reference/cli/index.md) and [API](../reference/api/index.md) docs.
|
||||
|
||||
For any information not strictly contained in these sections, check out our [Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
|
||||
For any information not strictly contained in these sections, refer to our [Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
|
||||
|
||||
## What is an image, template, dev container, or workspace
|
||||
|
||||
|
||||
@@ -142,4 +142,4 @@ See the [air-gapped deployments](../templates/extending-templates/modules.md#off
|
||||
|
||||
- See the [full example Docker template](../../../examples/jfrog/docker).
|
||||
|
||||
- To serve extensions from your own VS Code Marketplace, check out [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
|
||||
- To serve extensions from your own VS Code Marketplace, visit [code-marketplace](https://github.com/coder/code-marketplace#artifactory-storage).
|
||||
@@ -131,7 +131,7 @@ Some drawbacks include:
|
||||
Envbox requires the same kernel requirements as running sysbox directly on the nodes.
|
||||
Refer to sysbox's [compatibility matrix](https://github.com/nestybox/sysbox/blob/master/docs/distro-compat.md#sysbox-distro-compatibility) to ensure your nodes are compliant.
|
||||
|
||||
To get started with `envbox` check out the [starter template](../../../../examples/templates/kubernetes-envbox) or visit the [repo](https://github.com/coder/envbox).
|
||||
To get started with `envbox`, refer to the [starter template](../../../../examples/templates/kubernetes-envbox) or visit the [repo](https://github.com/coder/envbox).
|
||||
|
||||
<a id="authenticating-with-a-private-registry"></a>
|
||||
|
||||
|
||||
@@ -111,7 +111,7 @@ resource "coder_app" "zed" {
|
||||
|
||||
</div>
|
||||
|
||||
Check out our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
|
||||
Visit our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
|
||||
|
||||
## Environment variables
|
||||
|
||||
|
||||
@@ -131,4 +131,4 @@ Selecting **Cancel** falls back to the standard creation form where all paramete
|
||||
|
||||
### Example: Kubernetes
|
||||
|
||||
For a full example of the Open in Coder flow in Kubernetes, check out [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
|
||||
For a full example of the Open in Coder flow in Kubernetes, visit [this example template](https://github.com/bpmct/coder-templates/tree/main/kubernetes-open-in-coder).
|
||||
@@ -73,7 +73,7 @@ module "agent-firewall" {
|
||||
For examples of wrapping an agent or process such as Claude Code with Agent Firewall, see the [agent-firewall module README](https://registry.coder.com/modules/coder/agent-firewall#with-claude-code).
|
||||
|
||||
For a basic recommendation of what to allow for agents, see the [Anthropic documentation on default allowed domains](https://code.claude.com/docs/en/claude-code-on-the-web#default-allowed-domains).
|
||||
For a comprehensive configuration covering multi-language development, check out the [example policy](./example-policy.md).
|
||||
For a comprehensive configuration covering multi-language development, refer to the [example policy](./example-policy.md).
|
||||
|
||||
To load the policy from a `config.yaml` file in your template directory instead, pass it via `agent_firewall_config`.
|
||||
The module writes the config to the workspace and exposes the resolved path via `agent_firewall_config_path`, so everyone who launches Agent Firewall manually inside the workspace picks up the same configuration without extra flags.
|
||||
|
||||
@@ -108,7 +108,7 @@ The same control is available outside the dashboard.
|
||||
Use `coder templates create --agents-allowed=false` or `coder templates edit --agents-allowed=false <template>` for a single template.
|
||||
Use the search filter `agents-allowed:false` on `GET /api/v2/templates` to list the templates that block agents.
|
||||
|
||||
Check out [Template Optimization](./template-optimization.md) for best practices on writing discoverable descriptions, restricting template visibility, configuring network boundaries, scoping credentials, and designing template parameters for agent use.
|
||||
Refer to [Template Optimization](./template-optimization.md) for best practices on writing discoverable descriptions, restricting template visibility, configuring network boundaries, scoping credentials, and designing template parameters for agent use.
|
||||
|
||||
### MCP servers
|
||||
|
||||
|
||||
@@ -93,7 +93,7 @@ For more details, see [Configuring proxy settings for Copilot](https://docs.gith
|
||||
Add the AI Gateway Proxy CA certificate to your operating system's trust store.
|
||||
By default, VS Code loads system certificates, controlled by the `http.systemCertificates` setting.
|
||||
|
||||
Check out [Client Configuration CA certificate trust](../ai-gateway-proxy/setup.md#trust-the-ca-certificate) for details on how to obtain the certificate file.
|
||||
Refer to [Client Configuration CA certificate trust](../ai-gateway-proxy/setup.md#trust-the-ca-certificate) for details on how to obtain the certificate file.
|
||||
|
||||
When [TLS is enabled](../ai-gateway-proxy/setup.md#proxy-tls-configuration) on the proxy, add the TLS certificate to the system trust store as well.
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ The Coder server essentially runs a `terraform apply` every time a workspace is
|
||||
|
||||
> [!TIP]
|
||||
> Haven't written Terraform before?
|
||||
> Check out HashiCorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
|
||||
> Visit HashiCorp's [Getting Started Guides](https://developer.hashicorp.com/terraform/tutorials).
|
||||
|
||||
Here's a simplified diagram that shows the main parts of the template we'll create:
|
||||
|
||||
|
||||
@@ -7,6 +7,6 @@ These guides contain information on workspace management, workspace access via I
|
||||
These are intended for end-user flows only.
|
||||
If you are an administrator, please refer to our docs on configuring [templates](../admin/index.md) or the [control plane](../admin/index.md).
|
||||
|
||||
Check out [Dev Containers integration](./devcontainers/index.md) for running containerized development environments in your Coder workspace.
|
||||
Refer to [Dev Containers integration](./devcontainers/index.md) for running containerized development environments in your Coder workspace.
|
||||
|
||||
<children></children>
|
||||
Reference in new issue
Block a user