a recommended way to store user-readable change history

[dylang]

Currently when running npm update we get updates but we don't know what's actually changed.

It would be helpful if the next package repository site and the npm command line had a single recommend way to access and display changes.

The changes could be in a file like changes or changelog and would be referenced in package.json.

Ideally npm could read this file and show changes before or after npm update.

Apparently CPAN does something simular and might have good guidance for how this could work.

[autarch]

Alternatively, look for a Changes file in the tarball and show that. This will encourage people to write readable change logs like this - https://metacpan.org/source/DOY/Moose-2.0401/Changes

A list of commits is a poor substitute for a separate Changes file.

[dylang]

I forgot that I created this ticket. I created a module that will generate a changes file for any npm package on github:

https://github.com/dylang/changelog

It's both a command line app and a library that npm could use.

[autarch]

dyang, I think that tool could be the start of a useful Changes file, but I would hate to see the npm infrastructure encourage people to just dump their commit messages into the Changes file and upload.

The Changes file needs to summarize to be useful. This is especially important if we're dealing with more than a few commits.

The example I linked earlier shows this - https://metacpan.org/source/DOY/Moose-2.0401/Changes

A single bullet point may represent one, five, or twenty commits, but only one change that's relevant to consumers of the library.

[dylang]

I agree a hand procured change history is ideal, but currently we get nothing when updating, not even a link to a changes file if it exists.

Perhaps using the raw commit logs would be a bit noisy, but it would be better than the black box approach we have now, and it might even encourage more developers to spend the time updating a changes file.

[autarch]

I'll refer you back to CPAN, which I think is the state of the art of language-specific package repositories. CPAN's success is as much about culture as tech.

The expectation when you upload something to CPAN is that it includes a Changes file that you generate by hand. If you don't include one and people care about your module, they'll probably bug you about it (politely, I hope).

On the tech side, all that was needed was for the package repo search site to display the Changes file. Once that existed, the culture developed around that.

Having npm auto-generate (a mostly useless) Changes file doesn't help establish a good culture for the npm system.

[dylang]

Sounds good. I appreciate the suggestion of using what you've already seen working over my suggestion of trying what would essentially be a duct-tape hack. I'm changing the title of the ticket to reflect this.