Spelling skill: Add guidance about domain-specific vs. general terms#3924
Spelling skill: Add guidance about domain-specific vs. general terms#3924
Conversation
Co-authored-by: danieljurek <2158838+danieljurek@users.noreply.github.com>
Co-authored-by: danieljurek <2158838+danieljurek@users.noreply.github.com>
danieljurek
changed the title
danieljurek
force-pushed
the
copilot/add-cspell-file-selection-instructions
branch
from
7a39613 to
f44dd7b
Compare
danieljurek
requested review from
LarryOsterman,
RickWinter,
heaths and
ronniegeraghty
as code owners
There was a problem hiding this comment.
Pull request overview
Adds more explicit guidance to the spell-checking skill on where to place cSpell allow-list entries depending on whether a term is service-specific or shared across multiple services.
Changes:
- Adds decision guidance distinguishing domain-specific terms vs. cross-service terms for cSpell configuration.
- Specifies where to add words (
sdk/{service}/.cspell.jsonvs.vscode/cspell.json) and recommends alphabetical sorting.
| For words that should be ignored, add them to the `ignoreWords` array in a `.cspell.json` file under `sdk/{service-directory}` or lower. If the file doesn't exist, create it with an `import` of either a parent `.cspell.json` or `../../.vscode/cspell.json` from the root of the repo. | ||
| When ignoring a word, consider whether the word is domain-specific or spans multiple services: | ||
|
|
||
| 1. **It's a domain-specific term** (e.g., "RNTBD" in CosmosDB) unlikely to appear in other services — add it to the `ignoreWords` list in `sdk/{service}/.cspell.json`. Keep that list sorted alphabetically. |
There was a problem hiding this comment.
The placeholder/path guidance is inconsistent with earlier terminology in this document. Above you use sdk/{service-directory} (and even allow crate-level sdk/{service-directory}/{crate-directory}), but here it says sdk/{service}/.cspell.json. Please align the placeholder naming and consider whether this should also allow adding domain-specific terms at the crate directory level ("or lower"), consistent with the Configuration section.
| 1. **It's a domain-specific term** (e.g., "RNTBD" in CosmosDB) unlikely to appear in other services — add it to the `ignoreWords` list in `sdk/{service}/.cspell.json`. Keep that list sorted alphabetically. | |
| 1. **It's a domain-specific term** (e.g., "RNTBD" in CosmosDB) unlikely to appear in other services — add it to the `ignoreWords` list in the most specific relevant cSpell config, such as `sdk/{service-directory}/.cspell.json` or `sdk/{service-directory}/{crate-directory}/.cspell.json`. Keep that list sorted alphabetically. |
| When ignoring a word, consider whether the word is domain-specific or spans multiple services: | ||
|
|
||
| 1. **It's a domain-specific term** (e.g., "RNTBD" in CosmosDB) unlikely to appear in other services — add it to the `ignoreWords` list in `sdk/{service}/.cspell.json`. Keep that list sorted alphabetically. | ||
| 2. **It's a term that applies to multiple services** (e.g., "upsert") — add it to the `words` list in `.vscode/cspell.json`. Keep that list sorted alphabetically. |
There was a problem hiding this comment.
This has the risk of causing too many PRs to require approval form very few people with "god mode" permissions - for simple spell-checks jumping through teh hoops of getting these approvals often won't be worth it. Maybe instead only put it in the global exception if there is actual evidence that at least one other sdk/ already added an exception - that way the churn on global exceptions at least gets reduced?
heaths
left a comment
heaths
left a comment
There was a problem hiding this comment.
What I linked is more technical and easier to reason about.
| For words that should be replaced, fix the misspellings directly in the source files. If you cannot confidently determine the correct spelling, ask the user. | ||
|
|
||
| For words that should be ignored, add them to the `ignoreWords` array in a `.cspell.json` file under `sdk/{service-directory}` or lower. If the file doesn't exist, create it with an `import` of either a parent `.cspell.json` or `../../.vscode/cspell.json` from the root of the repo. | ||
| When ignoring a word, consider whether the word is domain-specific or spans multiple services: |
There was a problem hiding this comment.
A lot of this seems to vague. Sine the original skill was based on my original skill I've been using elsewhere and refining, I recommend something like this instead: https://github.com/heaths/plugins/blob/main/plugins/linting/skills/check-spelling/SKILL.md#choosing-the-correct-configuration-file-for-dictionary-words (that's where this came from originally).
Guidance for domain-specific terms in spell checking.