nock changelog

Created on 14 May 2020 · 7Comments · Source: nock/nock

Hello,
thank you for awesome tool.

https://github.com/nock/nock/blob/master/CHANGELOG.md

Nock’s changelog can be found directly in the GitHub release notes.

Problem

Decided to bump node and deps in legacy app, and npm outdated suggests me bumping nock from 9.6.1 to 12.0.3. As I have to read changelog first to easily avoid breaking changes, I googled nock changelog and got the link above. I went to 'releases' page, but it is full of beta versions and very unproductive to read. First thing I see now is huge "breaking change" note, but it is in beta, and sometimes beta code does not get into production, and anyway it is still beta, while I use production versions, so I spend time to analyze this row.

Proposed solution

Production-ready releases should have separate changelog file/whatever which is easily readable on single page. Meaning important things are pointed out.

I.e. examples of readable meaningful changelog: https://github.com/motdotla/dotenv/blob/master/CHANGELOG.md
https://github.com/sinonjs/sinon/blob/master/docs/changelog.md
Example of non-meaningful but still readble (single page) changelog:
https://github.com/eslint/eslint/blob/master/CHANGELOG.md

Sadly github releases page doesn't work this way :\

released released on @next

Source

glebsts

All 7 comments

I agree it’s really hard to catch up on many accumulated changelogs. I have run into this issue myself. Maybe there is a solution I’m not aware of with the current setup. It would be nice if conventional-changelog could generate this in a combined, readable format.

Alternatively as a workaround, we could collect links to the releases with breaking changes, and put those in the readme.

Curious your thoughts @gr2m

paulmelnikow on 14 May 2020

👍1

Since the readme is already pretty huge and I would expect most folks would check the changelog first, I think putting the links to the the major releases and migrations notes right in there would work.

There are no release notes before 9.0.23 😞

I would also be a fan of using github's wiki feature to have proper migration guide pages. The release notes mechanism just isn't user friendly for historical viewing.

mastermatt on 14 May 2020

Another option would be to check the migration guides into master, and add links in the changelog to those files in the master branch. I find it hard to keep up with changes on wikis so I'd probably prefer we go that route.

paulmelnikow on 14 May 2020

I like committing upgrade guides to the source code, too. It would allow people to contribute to it using pull requests. We could add short "breaking changes" summeries in the release notes, then link to the guides for more information, to avoid too much duplication