Spell-checking forces text of user issues to be changed in the release notes/

[CharliePoole]

I'd say this is fairly minor and depends on the policy of each project regarding spelling of the text in user issues.

My own policy in the engine project (and the whole project when I was responsible for it) was always to keep the exact text entered by the user unless it wasn't understandable at all. (In that case I'd change it and add a comment to the issue) I felt (and still do) that it was disrespectful to "correct" trivial errors made by the user...

The user descriptions live in the GitHub issues database. When creating releases, they are copied verbatim to the Release Notes on GitHub by an automatic process. Creating release notes on the website is currently a manual process, which I do using cut and paste from GitHub. In future, I would have wanted to automate it.

Whether done manually or not, however, the issue descriptions, which are listed in two places in GitHub are sometimes invalid for the release notes on the website and must be changed. This bothers me a bit because the description of a given issue is now in three places and one of them is different. I'd suggest eliminating spell checking on the release notes if that's easy to do.

[SeanKilleen]

Hi @CharliePoole,

You actually don't have to change the text.

there is a cSpell.json file in the root of the docs -- this configures "ignore words". Words added to the words list will be spellcheck suggestions. Words added to the ignoreWords list will not be suggested, but also will not raise errors.

When using tooling such as VSCode or the devcontainer, you would see a yellow squiggly line underneath with a quick shortcut to add something to the "dictionary". This saves a lot of the manual hunting.

If for some reason we had too many of these items and we didn't want to check the release notes file at all, we also have the option to ignore those files wholesale.

[SeanKilleen]

With that said, one thing that's clear from this is that the "docs for the docs" need a section on linting and spellchecking that explains the why/what/how for these common steps. Typically it's just me jumping in to help get thing over the finish line, but that's far from ideal.

[CharliePoole]

The cSpell.json file is only useful if you always want a particular spelling to be handled the same way. This is a bit different. It has to do that we are "quoting" someone else (the user) and don't necessarily want to change their spelling. In some situations, an editor would add [sic] to the quote.

The biggest problem I see with this is trying to figure out what to do after we change the text of an issue description. It's already spelled differently in the GitHub copy of the release notes and on the issue itself. I don't want to go back and change those entries.

Here's a possibility: Maybe release notes shouldn't be in two places at all!

[SeanKilleen]

In some situations, an editor would add [sic] to the quote.

OK, I see -- rather than a word that's "not in the dictionary", you're referring to a word that we know is misspelled in an issue.

My personal take on this scenario is:

• It's fine to correct spelling in the docs where warranted (though I do appreciate the manual tedium of doing this in the process above as you described)
• The issues / PR text don't need to also be updated. I don't think they need to be perfectly in sync especially since we have ID numbers and links.

Here's a possibility: Maybe release notes shouldn't be in two places at all!

That's how I feel about this in general. Release notes should live with the releases in GitHub. If anything, our docs could link to those release notes.

I'd be fine with either exempting release notes from spellcheck or moving away from release issues on the site in general (apart from a link to the GitHub releases).

[CharliePoole]

I think that just having the release notes on GitHub is the best solution. See below for a "but" :-)

I wanted to put this out there as an issue before I left. Up to you which way you decide to go.

Here is that "but"....

GitHub is the fourth repository host where NUnit has been hosted since 2000. One reason for release notes in the docs was to put them all in one place. However, nobody should be updating those old ones.