proposal: add a CHANGELOG.md

[mfridman]

I think we should keep a changelog for all changes landing on main, so when we go to do a release we can have up-to-date notes on the release.

I typically follow this convention, https://keepachangelog.com/en/1.0.0/

It'll be a bit more effort, but I think it's worth it so we don't miss anything, and users can see upcoming unreleased changes.

[oxisto]

Personally, I am a fan of the autogenerated changelog of GitHub and tried to avoid a manually written one just for the sake of extra work - but in general this is a good idea :)

[mfridman]

The issue with the GitHub-generated one is there are PR's that are not user-impacting, e.g., comments, changing tests, updating utilities, dependabot PR's (we don't have an deps, but still), etc. And these add noise to the release notes which gets fanned out to many users.

It'll be a bit more work for us, but overall this could be a more pleasant change for consumers of this library.

[mfridman]

Fwiw we can also automate it with something like GoReleaser. Where you push a tag, and a release (along with the notes from the CHANGELOG.md) gets published in an automated fashion.

Example: https://github.com/pressly/goose/blob/master/.github/workflows/release.yaml#L26-L31

We piggyback on GoReleaser, but only for the release process.

[mfridman]

I still think there's room for improvement when it comes to the changelog. For example, there's only a few substantial changes in the v5.1.0 release, and yet there's quite a bit of noise in the GitHub-generated changelog.

https://github.com/golang-jwt/jwt/releases/tag/v5.1.0

[oxisto]

I still think there's room for improvement when it comes to the changelog. For example, there's only a few substantial changes in the v5.1.0 release, and yet there's quite a bit of noise in the GitHub-generated changelog.

https://github.com/golang-jwt/jwt/releases/tag/v5.1.0

That is true, at least we could probably combine the refactor ones into a single item. As I said previously, I have nothing against the changelog, it is just basically a matter of some extra work. Do you think manually editing the Github release notes is enough or do you want to keep a separate file? We still have the legacy https://github.com/golang-jwt/jwt/blob/main/VERSION_HISTORY.md (which we should then either re-use or remove or rename?)