backdrop-ops / docs.backdropcms.org

Website for displaying Backdrop CMS documentation and API source code.
https://docs.backdropcms.org/
6 stars 6 forks source link

Add documentation of CSpell-supporting code annotations #231

Open bugfolder opened 10 months ago

bugfolder commented 10 months ago

Per https://github.com/backdrop/backdrop-issues/issues/6302, there are several things we might be doing in code to support CSpell spell-checking, e.g.,

If the word exists only in a 3rd party library that we are using and never or very rarely change, then consider ignoring the entire file/path in the ignorePaths section of our .cspell/cspell.json configuration file. Using cspell:disable-next-line or cspell:disable/cspell:enable pairs in these cases is impractical, as we shouldn't be changing 3rd party code (we'll loose those ignores if the library is updated in the future).

If the word is non-English (testing Unicode for example), the preference will be to ignore it with cspell:disable-next-line, or with cspell:disable/cspell:enable pairs when dealing with multiple lines where these words occur.

If the failure is for existing variable/function names or comments, then try to fix/rename those where possible/practical instead of adding more words to our dictionary - especially when these words are used only say 2-3 times in our entire codebase.

If the failure is for newly-introduced words in the PR, then:

try to fix those (split any combined words with dashes or underscores, or use camelCase for example) or, come up with alternative words that do not trip CSpell or, if the word is a made-up, fictional word used for testing purposes or as a documentation example, then see any existing fictional/test words in our dictionary can be used instead (if you are calling the thing pigglywiggly for example, then rename it to foobar which we have already added to our dictionary). or, if the word occurs multiple times in a single file, but you don't want to ignore the entire file, nor use dozens of cspell:disable-next-line, then consider ignoring the specific word(s) in the specific file, by adding an entry in the overrides section of our .cspell/cspell.json configuration file. Again, the goal will be to avoid adding more words to our custom CSpell dictionary where possible.

When fixing the codebase is not practical/possible, new words may be added to the dictionary. This will be able to happen without any core commit once we have moved our custom dictionary to its dedicated repo in https://github.com/backdrop-ops/cspell (refer to https://github.com/backdrop/backdrop-issues/issues/6280).

We should document CSpell-related code practices in our documentation, somewhere under Coding and documentation standards; perhaps adjacent to Naming Conventions.