From 7abe42afeaa67986d31046d75f5a2b9083e39f2d Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Wed, 15 Jul 2026 08:47:52 -0700 Subject: [PATCH 1/2] Scope CI spell-check to README and HISTORY by default The CI cspell gate ran over all `**/*.md`, which was never the agreed default: repos carry many markdown files full of technical terms, so gating every one of them means endlessly padding cspell.json just to keep CI green. The agreed default is README.md + HISTORY.md - the two files every repo visitor sees - with broad live spell-checking left to the cspell editor extension (any file, while editing). Narrow the cspell CI step to README + HISTORY, and codify the rule and its rationale in CODESTYLE.md "Markdown and Spelling" (the authoritative doc was silent on CI scope, which is why the workflow drifted). markdownlint stays repo-wide - it does not choke on technical terms. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/test-pull-request.yml | 7 ++++++- AGENTS.md | 2 +- CODESTYLE.md | 1 + 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-pull-request.yml b/.github/workflows/test-pull-request.yml index 05dff1e5..a7a389e2 100644 --- a/.github/workflows/test-pull-request.yml +++ b/.github/workflows/test-pull-request.yml @@ -30,10 +30,15 @@ jobs: with: globs: '**/*.md' + # Spelling gate is scoped to the two files every repo visitor sees. Broad spell-checking across all markdown is + # the cspell editor extension's job (live, any file); forcing all *.md through CI would mean endlessly padding + # cspell.json for every technical term. A repo may widen this list, but README + HISTORY is the shipped default. - name: Spell check step uses: streetsidesoftware/cspell-action@de2a73e963e7443969755b648a1008f77033c5b2 # v8.4.0 with: - files: '**/*.md' + files: | + README.md + HISTORY.md incremental_files_only: false - name: Lint workflows step diff --git a/AGENTS.md b/AGENTS.md index ef3f87f3..9fb49bfb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -233,7 +233,7 @@ CI runs the full lint set, but run the linters locally before pushing to catch i **Each surface runs the lint with the tool that fits it, all from the same config files** (`.markdownlint-cli2.jsonc`, `cspell.json`, `.editorconfig`): -- **CI (authoritative)** runs **markdownlint-cli2**, **cspell**, and **actionlint** as pinned action wrappers (Dependabot bumps them), plus **editorconfig-checker** via Docker `:latest` (its action only installs the CLI, so the Docker one-liner is what actually runs the check). +- **CI (authoritative)** runs **markdownlint-cli2**, **cspell**, and **actionlint** as pinned action wrappers (Dependabot bumps them), plus **editorconfig-checker** via Docker `:latest` (its action only installs the CLI, so the Docker one-liner is what actually runs the check). markdownlint covers all `**/*.md`; **cspell is scoped to `README.md` + `HISTORY.md`** (see [CODESTYLE.md](./CODESTYLE.md) "Markdown and Spelling" for why), matching the cspell one-liner below. - **The [`.husky/pre-commit`](./catalog/snippets/husky/pre-commit) hook** runs **language formatting only** - CSharpier + `dotnet format` (or ruff) via native tooling, no Docker and no doc linters, so it stays fast. - **The VS Code [Lint tasks](./catalog/snippets/configs/vscode-tasks.json)** run the full doc-lint set via Docker `:latest` on demand, the local surface for Markdown, spelling, workflow, and EditorConfig checks. diff --git a/CODESTYLE.md b/CODESTYLE.md index 51719477..30a33909 100644 --- a/CODESTYLE.md +++ b/CODESTYLE.md @@ -35,6 +35,7 @@ These apply repo-wide, in every directory: 1. **Markdown linting**: All `.md` files must be lint-clean (error and warning free) via the VS Code `markdownlint` extension. [`.markdownlint-cli2.jsonc`][markdownlint-cli2] at the repo root is the single source of truth - the davidanson `markdownlint` extension and a command-line `markdownlint-cli2` run both read it, so the IDE and CLI stay in lock-step. Rules it deliberately disables (e.g. `MD013` line-length, `MD033` inline HTML) are **intentional** - do not "fix" them. Fix violations at the source rather than disabling rules. 2. **Spelling**: All spelling must be clean via the CSpell VS Code integration; words must be correctly spelled in **US English** (the repo-wide convention - see [AGENTS.md][agents]). The shared `cspell.json` sets `"language": "en-US"` so British spellings are flagged - a bare `"en"` accepts both US and British and silently passes the wrong spelling. Project-specific terms go in the shared `cspell.json` `words` list - it is the single source of truth the extension, CLI, and CI all read. The `.code-workspace` must **not** carry its own `cspell.words`/`cSpell.words` block; when externalizing words into `cspell.json`, delete any word list left in the workspace (a leftover one duplicates the list and silently drifts). +3. **Spelling CI scope**: The enforced CI spell-check gate covers **`README.md` and `HISTORY.md` only** - these are the files every repo visitor sees, so they must be clean. It is deliberately **not** all `**/*.md`: repos carry many markdown files full of technical terms, and gating every one of them would mean endlessly padding `cspell.json` just to keep CI green. Broad, live spell-checking across any file (source, markdown, text) is the **cspell editor extension's** job, so typos still surface to whoever is editing. A repo owner **may** widen their own CI file list, but the template ships README + HISTORY as the default; keep the CI workflow, the `Lint: Spelling` VS Code task, and the AGENTS.md cspell one-liner on the same file list. Markdown *linting* (item 1) stays repo-wide `**/*.md` - it does not choke on technical terms. ## .NET From 0c673c9d618c4a779ec3aea2459c5fd1d54485a6 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Wed, 15 Jul 2026 08:52:29 -0700 Subject: [PATCH 2/2] Condense the cspell-scope comment to repo hygiene convention Copilot review: the comment exceeded the one-line-default convention. Trim to two lines and defer the full rationale to CODESTYLE.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/test-pull-request.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test-pull-request.yml b/.github/workflows/test-pull-request.yml index a7a389e2..0342e8b3 100644 --- a/.github/workflows/test-pull-request.yml +++ b/.github/workflows/test-pull-request.yml @@ -30,9 +30,8 @@ jobs: with: globs: '**/*.md' - # Spelling gate is scoped to the two files every repo visitor sees. Broad spell-checking across all markdown is - # the cspell editor extension's job (live, any file); forcing all *.md through CI would mean endlessly padding - # cspell.json for every technical term. A repo may widen this list, but README + HISTORY is the shipped default. + # cspell gate = README + HISTORY only; all-*.md would mean endlessly padding cspell.json for technical terms + # (broad live spell-check is the editor extension's job). See CODESTYLE.md "Markdown and Spelling". - name: Spell check step uses: streetsidesoftware/cspell-action@de2a73e963e7443969755b648a1008f77033c5b2 # v8.4.0 with: