From 6b694f96458145c151e0678d09758089ffa6a643 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Wed, 15 Jul 2026 08:54:37 -0700 Subject: [PATCH 1/2] Scope CI spell-check to README and HISTORY by default (#302) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Problem The CI cspell gate runs over all `**/*.md`. That was never the agreed default. The intended default is **README.md + HISTORY.md only** — the two files every repo visitor sees: - Repos carry many markdown files full of technical terms; gating every one through CI means endlessly padding `cspell.json` just to keep CI green — infeasible at fleet scale. - 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. The authoritative doc (CODESTYLE.md) was **silent** on CI scope, so the workflow silently drifted to `**/*.md` — and the whole local fleet inherited it. ## Change - **`test-pull-request.yml`**: narrow the cspell step from `**/*.md` to `README.md` + `HISTORY.md` (via the action's multiline `files:`). - **CODESTYLE.md § Markdown and Spelling**: codify the README+HISTORY default and its rationale (root-cause fix — gives future drift something to check against). - **AGENTS.md**: make the cspell CI scope explicit (README+HISTORY, matching the one-liner); note markdownlint stays repo-wide. `markdownlint` stays repo-wide `**/*.md` — it does not choke on technical terms. This is cspell-only. ## Follow-up This is the canonical (template) fix. A fleet sweep to narrow every downstream repo's CI cspell to the same default follows separately. ## Validation Local `actionlint`, `markdownlint-cli2`, and `cspell` all clean on the edited files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- .github/workflows/test-pull-request.yml | 6 +++++- AGENTS.md | 2 +- CODESTYLE.md | 1 + 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-pull-request.yml b/.github/workflows/test-pull-request.yml index 05dff1e5..0342e8b3 100644 --- a/.github/workflows/test-pull-request.yml +++ b/.github/workflows/test-pull-request.yml @@ -30,10 +30,14 @@ jobs: with: globs: '**/*.md' + # 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: - 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 1693f6044372dd216ef856c3b575d3da18788aa8 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Wed, 15 Jul 2026 09:22:29 -0700 Subject: [PATCH 2/2] Note the cspell gate scopes to whichever of README/HISTORY exists (#303) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Feedback from the ptr727/ProjectTemplate#302 fleet rollout: some repos (e.g. EspDinIoT, `releaseTrigger: none`) ship no HISTORY.md, and cspell errors on a listed file that does not exist. Clarify in CODESTYLE.md § "Markdown and Spelling" that the README + HISTORY default scopes to whichever of the two the repo actually has — a repo with no changelog gates on README.md alone. Docs-only. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- CODESTYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODESTYLE.md b/CODESTYLE.md index 30a33909..5172cabf 100644 --- a/CODESTYLE.md +++ b/CODESTYLE.md @@ -35,7 +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. +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. The list is explicit (not a glob), so a repo that ships no `HISTORY.md` (e.g. one with no changelog) must drop it from all three surfaces and gate on `README.md` alone - cspell errors on a listed file that does not exist. Markdown *linting* (item 1) stays repo-wide `**/*.md` - it does not choke on technical terms. ## .NET