From 90ac8f4d054162f6de7a73238a2354a29c78aaba Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Wed, 15 Jul 2026 10:41:10 -0700 Subject: [PATCH 1/2] Document the README + HISTORY cspell CI scope in CODESTYLE Propagate the CODESTYLE "Spelling CI scope" rule from the template (ptr727/ProjectTemplate#302, #303): the CI spell-check gate covers README.md + HISTORY.md, not all markdown, with broad live checking left to the editor extension. Co-Authored-By: Claude Opus 4.8 (1M context) --- CODESTYLE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CODESTYLE.md b/CODESTYLE.md index e145e50..9829356 100644 --- a/CODESTYLE.md +++ b/CODESTYLE.md @@ -36,6 +36,7 @@ These apply repo-wide, in every directory: 1. **Markdown linting**: All `.md` files must be lint-clean (error and warning free) against [`.markdownlint-cli2.jsonc`](./.markdownlint-cli2.jsonc) at the repo root, the single source of truth. The davidanson `markdownlint` VS Code extension and a command-line `markdownlint-cli2` both read it, and **CI enforces it** (the `lint` job runs `markdownlint-cli2`), so the editor, CLI, and CI 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**: Spelling must be clean in **US English** (the repo-wide convention - see [AGENTS.md](./AGENTS.md)). [`cspell.json`](./cspell.json) at the repo root holds the workspace config the CSpell VS Code extension and the CLI both read; it excludes the embedded multilingual data (`LanguageData/**`, the generated `*Data.cs`, build output) so that data is not flagged. **CI spell-checks the user-facing docs** (`README.md`, `HISTORY.md`) via the `lint` job; a whole-tree check stays in the editor. Add a genuine project term to `cspell.json` `words`; fix a real misspelling at the source. +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 From cc984234e90a92b4f5f10858ed07e4c5dd052164 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Wed, 15 Jul 2026 10:48:52 -0700 Subject: [PATCH 2/2] Reword the cspell-scope item to not name template-only surfaces Copilot review: the item referenced a Lint: Spelling VS Code task and an AGENTS.md cspell one-liner that exist in the template but not in this repo. Reword generically so the guidance is accurate regardless of which local cspell surfaces a repo actually has. 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 9829356..e2abce5 100644 --- a/CODESTYLE.md +++ b/CODESTYLE.md @@ -36,7 +36,7 @@ These apply repo-wide, in every directory: 1. **Markdown linting**: All `.md` files must be lint-clean (error and warning free) against [`.markdownlint-cli2.jsonc`](./.markdownlint-cli2.jsonc) at the repo root, the single source of truth. The davidanson `markdownlint` VS Code extension and a command-line `markdownlint-cli2` both read it, and **CI enforces it** (the `lint` job runs `markdownlint-cli2`), so the editor, CLI, and CI 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**: Spelling must be clean in **US English** (the repo-wide convention - see [AGENTS.md](./AGENTS.md)). [`cspell.json`](./cspell.json) at the repo root holds the workspace config the CSpell VS Code extension and the CLI both read; it excludes the embedded multilingual data (`LanguageData/**`, the generated `*Data.cs`, build output) so that data is not flagged. **CI spell-checks the user-facing docs** (`README.md`, `HISTORY.md`) via the `lint` job; a whole-tree check stays in the editor. Add a genuine project term to `cspell.json` `words`; fix a real misspelling at the source. -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. +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 every surface that runs cspell - the CI workflow and any local VS Code task or one-liner the repo has - 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