Skip to content

Latest commit

 

History

History
35 lines (22 loc) · 3.61 KB

advice.md

File metadata and controls

35 lines (22 loc) · 3.61 KB
Raw

Spell checking configuration advices

Basics

Since this action is an extension of check-spelling, make sure that you familiarize yourself with its concepts and configuration options first. Some of the most notable ones:

  • The spell checking process replaces matched words with a space character and built-in configuration files are checked first.
  • The order of entries within a configuration file matters.

Configuration files

Configuration files allow you to define words and patterns that shouldn't be considered spelling mistakes, e.g.:

  • allow.txt: Normal, expected words that just simply weren't added to the base or other referenced dictionary files yet.
  • excludes.txt: Perl-style regexes to ignore specific paths, files or extensions.
  • expect.txt: Dictionary file of arbitrary strings that aren't words, but otherwise valid and aren't spelling mistakes.
  • patterns.txt: Technical strings that aren't made up of words or word stems but follow a certain structure or pattern can be skipped using Perl-styled regexes. Some technical strings are already covered in Lombiq's version, such as hex color codes, Git commit hashes, GUIDs, and more.

You can provide these files in your own repository, but they must be placed under the path .github/actions/spelling. To ease maintaining dictionary files (and keep a consistent behavior), keep the entries sorted alphabetically.

When not to add entries to dictionary files

Before adding an entry to one of the dictionary files, consider the following:

  1. The order of entries in the spelling dictionary prefixes parameter in your workflow call matters, so the most specific ones, like your own should come before more generic ones, like "cspell".
  2. When confronted with unrecognized words in a spell checking report, consider which of those are actually words that make sense to type, instead of just being remainders (because some parts of the original text were replaced with a space character due to matching an earlier entry) of another word or a technical string.
  3. Also look at the execution log to see where the unrecognized entry is coming from to find out what the original text was in the code. The additional context can help determining how to handle the unrecognized entry.
  4. Rare cases that we don't expect to show up overall more than 3 times and strings that are valid in a single situation should be ignored in-place without adding them to a dictionary file. Placing the #spell-check-ignore-line string somewhere in a line (for example in a comment at the end of a line of code) will exclude that line completely from spell checking. In Markdown, add an HTML comment at the end of the line: <!-- #spell-check-ignore-line -->.

Helper scripts for local development

When using custom dictionary files on top of external ones (such as the ones from check-spelling or Lombiq's), these scripts can help reducing the number of entries you need to add to your own:

  1. Merge-SpellCheckingDictionaryFile.ps1: Use this to maintain your excludes.txt file by adding the entries from another file, while still keeping your own. To just remove duplicates and sort the entries alphabetically in a single configuration file, pass in the same file for both parameters.
  2. Optimize-SpellCheckingDictionaryFile.ps1: Use this to remove entries from your dictionary files that are already present in an external one you're referencing.