feat: npm changelog

[jefflembeck]

This is an RFC for npm changelog. This feature would allow a user to
easily see the changelog for a library.

Inspired by #7

[sindresorhus]

This also needs to support GitHub Releases. Many packages use that instead of a changelog file.

[sindresorhus]

Would be really useful if it could show a list of commits if there's no changelog.

[dantman]

"keep a changelog" also suggests NEWS and RELEASES.

[iarna]

The filenames listed here are the ones npm already guarantees will be published if they're present in the package directory. Adding new changelog filenames is, I think, out of scope for this RFC.

[dantman]

How about formatting .md files as Markdown and just falling back to text for everything else.

[dantman]

What is your expectation for when packages contain the following kind of changelog files?

• https://github.com/lodash/lodash/blob/master/CHANGELOG
• https://github.com/reduxjs/redux/blob/master/CHANGELOG.md
• https://github.com/reduxjs/react-redux/blob/master/CHANGELOG.md

[sholladay]

@dantman IMO the algorithm should support and prefer GitHub Releases. That would provide the best experience for redux and react-redux. In the case of lodash, I don't think npm should do anything fancy. Just treat it as a changelog and authors will fall in line. Trying to parse the changelog and follow it if it is a link seems like a rabbit hole to me.

[ljharb]

@sholladay I disagree; I think support for Github Releases should be secondary; there's no need to privilege github more than it already is, and better integration between Releases and changelogs is something Github itself should be solving. I think that if npm can address common changelog patterns, cohering a changelog with Releases is something the ecosytem can address pretty trivially.

[sholladay]

@ljharb so I actually agree with all of your points, but stand by my opinion on how the algorithm should be. GitHub gets a lot of preferential treatment in the npm CLI at the moment (perhaps too much, albeit I'm pretty happy with GitHub itself and the marriage it has with npm). That said, I've never had issues with using Bitbucket and npm together, for example, and I don't see any reason to believe this would be different with the changelog feature. npm should leverage GitHub's features while still providing a smooth experience to everyone else. If GitHub improves Releases as you mentioned it should, well I would love that, but I don't see these as being mutually exclusive, nor do I see it as something npm should count on when implementing this feature.

One of the main reasons preferring Releases will help npm's users is that they tend to be higher quality than changelog files, as evidenced by the example links that @dantman posted. I have encountered tons of projects like that. Releases tend to be crafted with more care. I think that when they are available, npm should use them.

[dantman]

@ljharb I agree.

Usage of GitHub Releases for changelog is very rare. I know of less than a half dozen packages that use GitHub releases to document changes. And a fair portion of them maintain a more detailed CHANGELOG file. And I only remember seeing large regularly updated frameworks use this pattern. i.e. I only see this pattern in projects that would be the easiest to convince to do some manual configuration in package.json.

IMHO among the smaller packages (the larger number of packages, which we should aim to have the best defaults for), changelogs as README sections are something I notice being used more often than GitHub Releases notes.

[iarna]

I have the same uneasiness about privileging Github that @ljharb does.

If we were to support Github releases I'd want to also support the same features in Gitlab and Bitbucket at least (the same way we do with shortcuts, eg, how we have both github:user/project and gitlab:user/project`).

We fill in releases for npm, but that's in addition to the changelog. I'd prefer we pave the changelog-as-file path to start and look at adding more facilities after that's done.

[zkat]

I'm also fairly comfortable decreeing that the CHANGELOG in the package is the One True Way, tbh.

[zkat]

We've decided to ratify this! We can bikeshed around a lot of small details, but the consensus with the dev team is that basing this off included CHANGELOG files (in their current included forms) is the best way forward. Specific behavior around npm changelog as far as display vs opening vs parsing TBD, but the core here is good.

Thank you Jeff! and thank you @dantman for getting this conversation rolling. 🎉