search

tape-testing / tape

tap-producing test harness for node and browsers
MIT License
5.77k stars 307 forks source link

Keep a changelog #517

Closed aral closed 8 months ago

aral commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

ljharb commented 4 years ago

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

r0mflip commented 4 years ago

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

r0mflip commented 4 years ago

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

ljharb commented 3 years ago

@customcommander that doesn’t help for a number of reasons; automatic releasing is dangerous and I’ll never permit that; and the commit convention messages aren’t customizable and i find the term “chore” to be toxic.

ljharb commented 8 months ago

Done in b467b85.