From 850afdc33f376016311f3cb68b74f622e2a5519d Mon Sep 17 00:00:00 2001 From: Daniel Jurek Date: Wed, 27 Oct 2021 10:00:02 -0700 Subject: [PATCH] Add spell check docs (#1945) * Add spell check docs * Add instructions for replicating CI behavior --- doc/common/spellcheck.md | 135 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 doc/common/spellcheck.md diff --git a/doc/common/spellcheck.md b/doc/common/spellcheck.md new file mode 100644 index 000000000..b4d1d5571 --- /dev/null +++ b/doc/common/spellcheck.md @@ -0,0 +1,135 @@ + +# Spell Checking the Azure SDK + +To keep code quality high we use a code scanner (cspell) to check for spelling errors in source and other files. To keep code quality high we check spelling in CI. These tools can be run locally as well. + +## Spell Check Locally + +Install the [Code Spell Checker vscode extension](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) locally. It will automatically spell check code according to configuration in the `cspell.json` file in the `.vscode` folder in the repo + +The cspell tool can also be run on the command line according to [instructions for cspell](https://github.com/streetsidesoftware/cspell/blob/master/packages/cspell/README.md). + +## Spell Check in CI + +We use [`cspell`](https://github.com/streetsidesoftware/cspell) in the CI environment to check for spelling errors. We use the `cspell.json` file in `.vscode` to configure the scan. + +CI checks only files which are changed. If some files are excluded in the `cspell.json` config those files will not be scanned even if they are changed. All spelling errors in a changed file will be reported, not just portions of the file that were changed for a particular PR. + +This behavior can be replicated locally by running from the root of the repo: + +```pwsh +./eng/common/scripts/check-spelling-in-changed-files.ps1 +``` + +## Fixing spelling errors + +### Requirements + +* NodeJS and NPM (installing the LTS version from https://nodejs.org/en/ will work) +* cspell (`npm install -g cspell`) https://www.npmjs.com/package/cspell + +### Procedure + +1. From the root of the repo run [`cspell` locally](https://github.com/streetsidesoftware/cspell/blob/master/packages/cspell/README.md) using the command: + +```pwsh +cspell lint --config .vscode/cspell.json --no-summary "/**/*" +``` + +To spell check only a certain set of files (like the public API surface), alter the expression to match: + +```pwsh +cspell lint --config .vscode/cspell.json --no-summary "sdk///api/*.cs" +``` + +2. Observe errors in console output and fix all errors. Re-run command as needed until all spelling errors are corrected. Notice that vscode, with the extension installed properly, will also highlight these errors in open files. + +#### Adding changes to files excluded by .gitignore + +If you add information to `.vscode/cspell.json` you may need to use a command like + +```pwsh +git add -f .vscode/cspell.json +``` + +to add changes in the file to your commit. + +***BE CAREFUL CHECKING IN CHANGES TO FILES IN .gitignore*** -- expressions in .gitignore may be there to prevent checking in credentials or information that would alter configurations for other contributors. Make sure you check each change that goes into those files. + +#### Performance + +If spell checking takes a long time look at performance information in the console output to see if cspell is spending a long time looking at files for whom spelling is not important (e.g. build output binaries, test session recordings, etc.). Add glob expressions of these files to `ignorePaths` to improve performance. + +### Example CI Output + +Look for "Unknown word" in the spell check run log to find spelling errors + +``` +... +232/372 ./sdk/storage/storage-file-datalake/src/models.internal.ts 12.98ms +233/372 ./sdk/storage/storage-file-datalake/src/policies - +234/372 ./sdk/storage/storage-file-datalake/src/sas - +235/372 ./sdk/storage/storage-file-datalake/src/transforms.ts 82.74ms +236/372 ./sdk/storage/storage-file-datalake/src/utils - +237/372 ./sdk/storage/storage-file-datalake/src/utils/cache.ts 17.26ms +238/372 ./sdk/storage/storage-file-datalake/src/utils/tracing.ts 23.29ms +239/372 ./sdk/storage/storage-file-datalake/src/utils/utils.browser.ts 28.80ms +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:8:37 - Unknown word (Helvetica) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:8:47 - Unknown word (Neue) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:8:54 - Unknown word (Helvetica) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:98:14 - Unknown word (tbody) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:101:19 - Unknown word (vsts) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:108:19 - Unknown word (vsts) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:117:179 - Unknown word (noopener) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:117:188 - Unknown word (noreferrer) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:126:168 - Unknown word (noopener) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:126:177 - Unknown word (noreferrer) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:135:166 - Unknown word (noopener) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:135:175 - Unknown word (noreferrer) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:144:166 - Unknown word (noopener) +/home/vsts/work/1/s/sdk/storage/storage-file-datalake/storage-file-datalake-lintReport.html:144:175 - Unknown word (noreferrer) +... + +``` + +### False positives + +If spell check is showing a false positive for a particular word use the strategies in [cspell documentation](https://github.com/streetsidesoftware/cspell/blob/master/packages/cspell/README.md) to configure cspell to ignore the word. + +Strategies include: + +* Using [in-document settings](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell#in-document-settings) to ignore the error -- These settings are scoped to the particular file and are most useful when ignoring an error which appears in a specific file that you may want to highlight in other places +* Using [cspell.json settings](https://github.com/streetsidesoftware/cspell/blob/master/packages/cspell/README.md#cspelljson-sections) + * `words` -- If the word is correct and should be considered correct throughout the codebase (e.g. it is a product name) add the word to this section + * `ignorePaths` -- Use this to exclude paths or files that should be ignored. For example, `.dll` files should not be spell checked because they have no interesting human readable content when treated as a text file + * `overrides` -- Use this option to apply specific rules to a set of files. Scope the rules appropriately (e.g. to the service) and do not exclude all of a given type of file (e.g. `*.cs` in .NET). An example override to add `xzample` as a word in .cs files for the storage service: + +```json + ... + "overrides": [ + { + "filename": "sdk/storage/**/*.cs", + "words": [ + "xzample" + ] + }, + ... + ]... +``` + + * `ignoreRegExpList` -- Use this feature carefully to exclude common expressions which might be mistaken for words (e.g. compiler flags that have preceding letters `-Dsome_config`). USING INAPPROPRIATE EXPRESSIONS MAY CHANGE HOW ALL SPELL CHECKING IS HANDLED FOR THE ENTIRE REPO. Please use other approaches if possible because incorrect regular expressions can generate false positives or break spell checking for some or all of the repo. + +### Contributors + +We sometimes credit external contributors in our `CHANGELOG.md` files. In these cases add the user's alias directly to an override for CHANGELOG.md files. The CHANGELOG files are mostly prose and highly visible to customers, it makes sense to spell check the rest of the file and not ignore it. + +```json +{ + ... + "overrides": { + "filename": "**/CHANGELOG.md", + "words": ["", ... ] + } +... +} +```