Ideas for "Best Practices" with this extension, and documenting v2.0.7 behavior

[ryan-feeley]

Hi, this is just some ideas about how to use this extension in VS Code, as documentation is always a pain, and I know the lead dev just did a major version release and I'm sure has plenty to do to keep up with all the vs code changes under the hood.

I think the best usage model is to pattern-match of what is done in the repo source itself. Namely:

• Create a cSpell.json configuration file that you use to manage your dictionaries
• When you white-list individual words, add them to this config: <file>, not any of your VS Code Settings files.
• Put each dictionary in a *.txt file, following the format described here.
• Explicitly import the cSpell.json into your *.code-workspace file, rather than let the extension search for it.
• Use the ${workspaceFolder:<name>} variable in your paths

The extension supports a lot of use-cases, with at least four different places to store added words. This is a big state-space to grok, so I think the white-list aspects work best if you follow steps above. This keeps most of the word white-listing and configuration to dictionary.txt files and cspell.json files that are completely managed by the extension. Then the VS Code can just pull in the cspell.json from your user/workspace/workspace-folder settings. This might sort of violate the ethos of VS Code settings files, but consider that your whitelists probably change very often during your development, so in terms of code commits and the like, separating the white-lists from your settings/workspace settings makes sense, since these have different development cadences.

Here is some behavior that I've observed. Recall there are multiple contexts in which you can be using VS Code:

1. You've opened one or more files
2. You've opened a folder, which implicitly generates a "workspace" under the hood that is used at minimum as a database entry that will preserve the list of files you have open in the editor if you open that folder again in the future. If you apply workspace-level settings in this mode, VS Code will auto-generate a .vscode/settings.json file inside your folder to store such settings.
3. You've opened a *.code-workspace file. This opens a workspace explicitly, and that file serves as the place where any workspace-level settings are stored. However, for any of the root folders listed in the *.code-workspace file (there should always be at least one) you can also make folder-specific settings. These are made as if you'd opened just that folder in VS Code. A /.vscode/settings.json file is autogenerated that will house the folder-specific settings. Be aware that Workspace-Folder settings take precedent over *.code-workspace settings when you're editing files in the associated folder, and that includes your whitelists. THEY ARE NOT MERGED.

If you RMB anywhere in the editor to access the context menu, you’ll see two vscode-spell-checker options, which behave differently depending on with of the 3 contexts you're working in.

Given this behavior, I'll make the following recommendations:

1. Try to open folders, rather than individual files. This gives you more options for how to white-list words.
2. Always generate a "CSpell Configuration File". If you just have a short list of words to white-list, let the extension add them to it directly. If you anticipate a longer list, Create a Custom Dictionary after you have a configuration file, and link that dictionary to the CSpell Configuration File, rather than directly to either your User, Workspace, or Workspace-Folder settings.

Behavior when using the Extension to add or ignore words.

You've Opened One or More Files

If you open a file in VSCode, by default no spell checking is performed because VS Code defaults to opening a file as “untrusted”. You can enable Workspace Trust for the current VS Code Window to activate spell checking.

With spell checking active, I observe the following behaviors:

You've Opened a Folder (Implicitly creating a Workspace)

If you add a dictionary and link it to a Workspace, you may see an error "Unable to write cSpell.customUserDictionaries" to workspace settings. However, it actually works fine. ./.vscode/settings.json is automatically created, and a cSpell.customDictionaries setting is added to this file. The addWords field defaults to true, so this dictionary will be used as the default "dictionary" to add words to.

If you first add a CSpell Configuration File, and then add a dictionary that you associate with the CSpell Configuration File, most of the white-list operations will use that dictionary, but if you "Add Words to Workspace Settings", you'll have a ./.vscode/settings.json file autogenerated that is used to store Workspace-level words.

If you don't add a Dictionary or a CSpell Configuration file, I observe the following behaviors:

You've Opened a code-workspace file

Here the *.code-workspace file serves as the natural place to store workspace settings, so you can expect that ./.vscode/settings.json files won't be autogenerated.

However, there is a gotcha with this behavior. If you do "add to folder settings", and you don't have any folders in your workspace other than the root folder, then that action will autogenerate a ./vscode/settings.json file. This can create confusion because VS Code defaults to giving Workspace-Folder settings higher priority than settings defined in a *.code-workspace file. As a consequence, the "root-level folder settings" will shadow the main workspace level settings, and cause its whitelists to be ignored. This is probably not what you want. I think the solution here is to never do "Add to Folder Settings" unless you know have setup your project such that it is a multi-root workspace, and make sure you don't inadvertently add any folder-level settings that completely shadow settings in the main code-workspace file.

I hope this is a helpful discussion. I'm not sure I'm totally on the right track with how the extension is meant to be used, but these are my ideas at the moment. Let me know what you think!