Consider using CHANGELOG.md again?

[tony]

Hi! 👋

Sorry for the non-technical issue / bikeshed!

No one else has made this issue other than me at this time (so I can see), so it may just be personal taste. I have a preference toward CHANGELOG.md files, but want to explain why.

Is your feature request related to a problem?
To me, it feels difficult to track changes made to the packages across versions when updating downstream with GitHub Releases, as opposed to CHANGELOG.md.

Describe the solution you'd like
Continue to maintain a curated CHANGELOG.md file as in v3.2.0 and earlier. This would be very well appreciated.

It doesn't necessarily mean disabling or stopping GitHub Releases, just continuing to keep the changelog updated.

Describe alternatives you've considered
The use case here is downstream package user (me) updating the package across a span of versions. Also I am attempting to make the release notes easily available to reviewers 😄:

Before (Prior to 3.2.0):

A single link to a tag could explain the changes: https://github.com/IanVS/prettier-plugin-sort-imports/blob/v3.2.0/CHANGELOG.md. The user can scroll down to see changes between a span of versions.

Now (After 3.2.0):

The downstream experience is different: I open GitHub Releases, then find the link to each final GitHub release (all the while skipping prereleases and paginating when needed):

• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.1.1
• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.1.0
• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.0.2
• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.0.1
• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.0.0
• Since prereleases aren't useful, I don't link to them (but still scroll past them on the releases page):
  • https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.0.0-beta.0
  • https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.0.0-alpha.7
  • https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v4.0.0-alpha.6
  • So on
• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v3.7.2
• https://github.com/IanVS/prettier-plugin-sort-imports/releases/tag/v3.7.1

Then, a reviewer would need to open each link individually, rather than scroll. I don't believe GitHub releases can provide a link with a range of versions (correct me if I'm wrong).

Additional context

The release notes, as you have them, by my definition are very good quality (e.g. Breaking changes are at the top, like in v4.0.0 shows a lot of conscientiousness as a maintainer toward downstream users in showing what would impact them).

My issue is GitHub Releases itself. It's format is very tedious compared to merely keeping a changelog file.

Thank you once again for the project!

[IanVS]

Thanks for raising the issue. We do indeed try to put some thought into the release notes, and I agree that sometimes it's nice to have a changelog in a single file. However, it does increase the maintenance burden a bit, and it complicates the release process.

That said, I'd be willing to accept a PR that updates the CHANGELOG.md with the releases between 3.2 and now, and can keep it updated on a best-effort basis.

I'm also willing to explore a more systematic approach such as changesets, though that seems like it could be overkill for a small project like this which I don't expect to have frequent releases.

[fbartho]

For what it’s worth, I found other automated Changelog tools were a huge friction for new contributors to a repo. Though I haven’t used changesets in particular. (I think the most annoying were ones that required a certain commit subject format on every commit).

One successful project I saw (who I now can’t remember) used DangerJS to automatically ensure every PR had an entry in the Changelog.

• If the link to the PR wasn’t present, it was a lint warning (though we could auto-commit a default entry)
• When the link to the PR was present it did nothing (allowing you to write a different subject than the PR’s subject, or coalesce multiple PRs into a single bullet-point).

I’m not sure it’s worth all the hassle though, unless we expect this repo to see a lot of ongoing development? — The best-effort basis might be sufficient.

[jasikpark]

^ changesets has a similar lint for PRs, and allows easy addition of a changeset to a PR by the maintainers, ex: jasikpark/astro-svg-loader#86 (comment) allows you to click on the "add a changeset" link, which lets you add a changeset to the PR via the GitHub UI