mirror of
https://github.com/coder/coder.git
synced 2026-11-03 14:21:04 +08:00
Nick Vigilante
4d4d2575e4
## Problem The repo-root `.vale.ini` lints all of `docs/**/*.md`, including the style guide under `docs/.style/style-guide/`. The guide deliberately contains the constructs the Coder rules ban: - Don't examples in blockquotes and in the Don't column of Do/Don't tables. - Banned terms named in prose and headings (a rule about "Next steps" must write "Next steps"). `Coder.BrandNames` already fired on the Brand names table's Don't column (`Hashicorp`, `HASHICORP`), and each future `Coder.*` rule would fire on its matching section's examples. Vale runs advisory, so these surface as non-blocking annotations, exactly the standing backlog the README warns against, and they break the documented "zero baseline findings" doctrine. ## Change Option B, narrowed after review to the style-guide subtree: - `.vale.ini`: clear `BasedOnStyles` for `docs/.style/style-guide/**` (the guide subpages only). The annotation demo and the rest of `docs/.style/` stay linted; the demo keeps firing its `Coder.Demo*` rules by inheriting `Coder` from `[*.md]`, with no re-include. Also corrects the `error`-tier doctrine line to reflect advisory-only Vale. - `docs/.style/README.md`: "What still runs" / "What does not run" describe the narrowed exemption, and record that it holds only for paths that resolve to `docs/.style/style-guide/...` (repo-root-relative), not absolute or subdirectory-relative invocations. - `docs/.style/style-guide/README.md`: exemption note scoped to `docs/.style/style-guide/**`. - `docs/.style/styles/Coder/BrandNames.yml`, `docs/.style/styles/Coder/README.md`: fix the remaining dead `style-guide.md` links (the `BrandNames.yml` one was a live 404 surfaced in Vale annotations). ## Validation - `make lint/prose` reports only the 3 intended `Coder.Demo*` findings across the corpus; the guide's `BrandNames` findings are gone. - `content-guidelines.md`, the landing `README.md`, and `styles/Coder/README.md` are now linted and clean (0). Injecting a miscased `Hashicorp` into `content-guidelines.md` fires `Coder.BrandNames`; reverted. - The guide subpages stay exempt (0); the annotation demo still fires its 3 findings via `[*.md]`. - Invocation-path behavior verified against `docs/.style/style-guide/word-choice.md`: repo-root-relative `docs/...` is exempt (0), while `docs/`-relative and absolute-path invocations still fire 2 `Coder.BrandNames` errors. - `markdownlint-cli2` clean on the changed READMEs. ## Decision log Considered three options from the issue: - **A. Surgical in-file suppression** (`vale off`/`vale on` comment blocks, backticking banned terms). Rejected as primary: noisy in source, repeated per example, bare-term headings still fire, and every new rule can re-break the guide. It is path-independent, so it would have covered the editor case noted in Option B's limitation. - **B. Config-level subtree exemption** (chosen; narrowed to the guide subtree after round-2 review). One place, zero source noise, future-proof for the guide subpages. - **Scope.** The clear applies to `docs/.style/style-guide/**` only. Round-2 review (three reviewers converged, verified end-to-end) showed the original directory-wide clear over-reached: `content-guidelines.md` and the landing `README.md` are ordinary contributor prose that lints clean today (`content-guidelines.md` uses `HashiCorp` correctly), so they should stay linted. Narrowing to the guide subtree preserves the exact 3-finding baseline, relints those two pages, removes the last-match-wins ordering hazard, and drops the whole-package demo re-include. The demo sits at the `.style/` root and keeps firing via `[*.md]`. - **Tradeoff.** The guide's own prose under `style-guide/` is no longer auto-linted by Vale. Acceptable because the guide must contain banned terms by design, one-sentence-per-line is enforced by markdownlint, and human review covers the rest. - **Limitation.** The exemption holds only for invocations whose path resolves to `docs/.style/style-guide/...` (repo-root-relative `docs/...`, what `make lint/prose` and CI pass). Absolute paths (editors/LSP) and subdirectory-relative paths still flag the guide. Recorded in `docs/.style/README.md`. - **C. Restructure examples into fenced code blocks.** Rejected: changes the guide's rendered format and doesn't cover Do/Don't tables or headings. ## Notes - `.vale.ini` is outside `docs/`, so this PR modifies repo-wide lint config; the clear is scoped to `docs/.style/style-guide/` only. - Linear: DOCS-543. --- Opened via Coder Agents on behalf of @nickvigilante.
29 lines
1.2 KiB
YAML
29 lines
1.2 KiB
YAML
# Coder.BrandNames - enforce canonical brand-name casing in prose.
|
|
#
|
|
# Vale's substitution rule applies in prose only; it skips fenced code
|
|
# blocks, inline code, and URLs by default. That means `hashicorp/kubernetes`
|
|
# (Terraform provider source) and `developer.hashicorp.com` (URL) stay
|
|
# untouched. The rule fires on body text and headings where the wrong
|
|
# casing appears as a normal word.
|
|
#
|
|
# Level: error. Each swap targets a brand whose owner publishes a
|
|
# canonical casing; "Hashicorp Vault" instead of "HashiCorp Vault" is
|
|
# objectively wrong, not a judgment call. The existing-content violation
|
|
# count is zero (cleanup landed in the previous commit), so this rule
|
|
# can ship at error from day one.
|
|
#
|
|
# Adding a brand: append a key/value to the swap table below and audit
|
|
# the docs corpus for the wrong-casing variant. Keep the message template
|
|
# unchanged; the `%s` token interpolates the matched (wrong) text.
|
|
extends: substitution
|
|
message: "Use '%s' instead of '%s' (brand-name casing)."
|
|
link: https://github.com/coder/coder/blob/main/docs/.style/style-guide/word-choice.md#brand-names
|
|
level: error
|
|
ignorecase: false
|
|
nonword: false
|
|
action:
|
|
name: replace
|
|
swap:
|
|
Hashicorp: HashiCorp
|
|
HASHICORP: HashiCorp
|