mirror of
https://github.com/coder/coder.git
synced 2026-11-01 21:13:14 +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.
1.5 KiB
1.5 KiB
Coder custom Vale rules
Custom Vale rules specific to Coder live here.
Each rule is a YAML file that Vale loads through the BasedOnStyles = Coder setting in the repo-root .vale.ini.
Active rules ship as YAML files in this directory.
See the matching sections in docs/.style/style-guide/ for the user-facing policy each rule enforces.
Follow-up PRs add rules incrementally.
Planned coverage:
- Dev Container terminology
- Limit
we - Setup vs set up, Quickstart casing
- Next steps vs Learn more
- Vale substitution rule scaffold
- Weasel words
- Em-dash and en-dash mirror in Vale
- Inclusive-language substitutions
- Product-voice rules
Authoring a new rule
- Write a YAML file under this directory. Name it after the rule's
intent, for example
InclusiveLanguage.ymlorProductVoice.yml. - Each rule's
message:should link to the matching section in the appropriate subpage ofdocs/.style/style-guide/, ideally with a deep-link anchor, so a contributor reading a Vale warning can jump straight to the guidance. - Land at
level: warningfirst. Promote tolevel: erroronly after both conditions hold:- The rule is objectively correct (typo, brand-name casing, banned substitution).
- The existing-content violation count for the rule reaches zero.
- A follow-up PR adds a parity CI check that verifies every rule here has a matching section in
style-guide/. Add the section in the same PR as the rule.
Reference
- Vale docs: https://vale.sh/docs/
- Vale rule types: https://vale.sh/docs/topics/styles/