mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +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.
43 lines
1.9 KiB
INI
43 lines
1.9 KiB
INI
# Vale configuration for Coder documentation.
|
|
#
|
|
# Rule rollout doctrine. Every rule listed below ships clean: zero
|
|
# baseline findings across `docs/` (excluding `docs/.style/style-guide/`,
|
|
# which is exempt by design; see docs/.style/README.md) at enable time.
|
|
# Severity is a deliberate per-rule choice:
|
|
#
|
|
# - `error` top annotation tier; surfaces a GitHub `error`. Vale
|
|
# runs advisory, so it does not block merge today.
|
|
# - `warning` strong guidance; surfaces annotations without
|
|
# failing CI.
|
|
# - `suggestion` soft guidance; surfaces `notice` annotations.
|
|
#
|
|
# To add a rule, follow the per-rule PR template in
|
|
# docs/.style/README.md ("Adding a Vale rule"). Third-party rules
|
|
# from Google, alex, and write-good are not enabled by default; each
|
|
# returns via the same per-rule PR pattern after its corpus is clean.
|
|
#
|
|
# About Vale's exit code: Vale exits non-zero only when error-level
|
|
# alerts are found. Warning and suggestion annotate without
|
|
# affecting exit. Real runtime failures (bad config, missing files)
|
|
# propagate regardless of severity.
|
|
#
|
|
# The Coder rule package lives under docs/.style/styles/Coder/ and is
|
|
# the single source loaded by default.
|
|
|
|
StylesPath = docs/.style/styles
|
|
MinAlertLevel = suggestion
|
|
|
|
[*.md]
|
|
BasedOnStyles = Coder
|
|
|
|
# The style guide under docs/.style/style-guide/ deliberately demonstrates the
|
|
# violations the Coder rules ban (Don't examples in blockquotes and Do/Don't
|
|
# tables, banned terms named in headings and prose). Linting it would surface a
|
|
# standing backlog of intentional findings, which erodes trust in the annotation
|
|
# channel and breaks the zero-baseline doctrine. The rest of docs/.style/ (the
|
|
# landing page, content-guidelines.md, the annotation demo, and the Coder rule
|
|
# docs) is ordinary prose and stays linted; the annotation demo keeps firing its
|
|
# Coder.Demo* rules with no re-include. See docs/.style/README.md.
|
|
[docs/.style/style-guide/**]
|
|
BasedOnStyles =
|