The release changelogs are painful to read as a user

[djmattyg007]

The changelogs are incredibly difficult to read as a user. I'm not sure what information I'm supposed to gain by reading fix: Workflow Bot -- Update Dictionaries (main) by @street-side-software-automation literally 19 times in the v7.0.0 release notes. Is this something I need to care about as a user of the library? I have no idea how to tell because there's zero context around the changes in the release notes. I don't really want to have to dig into 19 separate PRs with identical names just to work that out. If the dictionaries were updated multiple times between two releases, I would expect to see just one entry in the changelog (with links to multiple PRs if necessary, should I want to dig into the detail).

The v7.0.0 release notes also don't make it clear if there are any breaking changes for people who only use cspell as a CLI tool and not as a library. There is a note about a breaking change to do with the internal structure of the trie, but there is no link (or other reference) to more information to help me understand if I may be affected.

I'm also very confused about the purpose of CHANGELOG.md - it doesn't contain anywhere near the amount of detail as the Github releases do, and they don't mention the breaking changes at all:

https://github.com/streetsidesoftware/cspell/blob/main/CHANGELOG.md#700-2023-08-10

I'm hoping to roll out cspell at the company I work at, but if I can't point to any solid documentation about breaking changes when they do happen it's difficult to justify why we should be using a tool like this :(

[Jason3S]

@djmattyg007,

Thank you for the feedback. I agree, the CHANGELOG.md is hard to decipher. It is automatically generated from the pull requests.

You make a good point about the release notes not calling out how moving from v6 to v7 will impact the CLI user experience (I will adjust them). The main impact is to require Node 16+. Other than speed improvements, the rest are internal changes that would impact API users.

As a general rule, CSpell follows Semantic Versioning. The release of v7 was delayed to reduce the number of major version increments due to API changes. As a result, you are seeing a lot of "dictionary" updates. These generally have a very minor impact to an existing CSpell setup since they mostly just include added words. To ensure dictionary updates are a seamless experience for end users, extensive integration tests are done to ensure there are no surprises. Workflow automation is used extensively to verify that each change works as expected.

I hope this helps.

Kind regards.

[djmattyg007]

It sounds like the solution is to stop auto-generating changelogs that are very difficult for users to read, and to instead have a human write a changelog for other humans.

[Jason3S]

@djmattyg007,

If having hand written changelogs and release notes is important to you, please consider opening a monthly support contract. That way we can better meet your needs.

A corporate sponsorship would also be welcome:
.

Kind regards.