Skip to content

Latest commit

 

History

History
135 lines (96 loc) · 7.76 KB

spellcheck.md

File metadata and controls

135 lines (96 loc) · 7.76 KB
Raw

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 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.

Spell Check in CI

We use 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:

./eng/common/scripts/check-spelling-in-changed-files.ps1

Fixing spelling errors

Requirements

Procedure

  1. From the root of the repo run cspell locally using the command:
cspell lint --config .vscode/cspell.json --no-summary "<your-path>/**/*"

To spell check only a certain set of files (like the public API surface), alter the expression to match:

cspell lint --config .vscode/cspell.json --no-summary "sdk/<your-service>/<your-package>/api/*.cs"
  1. 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

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 to configure cspell to ignore the word.

Strategies include:

  • Using 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
    • 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:
    ...
    "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.

{
  ...
  "overrides": { 
    "filename": "**/CHANGELOG.md",
    "words": ["<external-contributor-alias>", ... ]
  } 
...
}