Keep a changelog

[aral]

Use case

Version 5.0.0 is a semver major update with breaking changes but I don’t know where to look for those breaking changes. A changelog would be the first place I’d normally look.

https://keepachangelog.com/en/1.0.0/

Workaround

Do a search in the issues for people reporting breaking changes: https://github.com/substack/tape/issues?q=is%3Aissue+breaking

[aral]

OK, found them: https://github.com/substack/tape/releases/tag/v5.0.0

Not sure if I looked at a different tag previously. Closing since you already have a comparable system in place.

[Raynos]

Having breaking changes in a specific markdown file in the repo that we update for every major is beneficial.

The full changelog can stay in git releases.

I like a MIGRATION.md ( https://github.com/optoolco/tonic/blob/master/MIGRATION.md ) where instead of listing breaking changes you document how to migrate and "upgrade/fix" your old code for each breaking change.

[ljharb]

I’m very much in favor of a CHANGELOG.md file; i haven’t yet found a tool that can autogenerate this repo’s precious releases, including backports, properly, and the effort to manually create it is prohibitive. In the meantime, GitHub’s “releases” feature, and specifically, every tag, has release notes for that tag.

For tape, migrating is generally pretty straightforward - that doc would pretty much just contain tips about loose vs strict, and so forth.

[r0mflip]

Is querying GitHub API for all the releases/tags and using the response to build a HISTORY.md style file prohibitive?

[ljharb]

@r0mflip point me to a package that does that, and i'll use it :-)

[r0mflip]

It might exist in an alternate universe but in ours, we probably have yet to create it 😛

[r0mflip]

@ljharb So, I made one https://github.com/r0mflip/logtag

[ljharb]

Done in b467b85.