Try generated changelog

[sam-github]

Clearly, just my opinion, and if you all love the changelog strategy as it is, I've no problem working with it, but here's a shot at making the case that better tooling is a better way to go.

The keep-a-changelog stance doesn't look very tenable for projects like this, unlike a web framework, say, or an app, where someone would do a nice writeup for every release, giving guidance and information on what's changed, maybe some blog posts, etc, etc.

AFAICT, what is actually happening is that the git commit description is pasted by hand into the CHANGES.md file. This has downsides:

1. Its non-standard, it used to require a reminder on every PR from the maintainers, though now the reminder is automated with a github action, which is better for reviewers, but same for contributors
2. It doesn't appear to result in a better changelog, I don't think the existing changelog is noticably more informative than an autogenerated one
3. Every PR is guaranteed to conflict if anything is merged before it, because the changelog centralizes conflicts. This requires manual conflict resolution by either maintainers from CLI, or the PR people, its just one extra step.

The first commit in this draft shows what the auto-generated changelog could look like -- I obviously used the tooling I used when I was maintaining and releasing scores of packages simultaneusly, but there are many spins on this.

The second commit goes a step further, it shows what a one shot slt-release -up vx.y.z would look like (except without the -up, which would do a git push and npm publish -- one-shot command for an entire release. could probably even be a GH action...). The tedious details are in the docs, but basically, it uses npm version to update the package version, uses the auto-generated log (for changes since last release) as the commit message and tag message (which is what shows up on the prom-client/releases page), etc.

Offerred for your consideration! :-)

cf. #344

[siimon]

This looks great in my opinion, the more automation the better! The only missing detail that is required in the current changelog is what kind of change it is (like a breaking change or a change in behaviour), in this version it is up to the contributors to put in the commit message. For me personally I don't see any problems with removing that information in the changelog.

I'd love an automated way of making the releases too since it's just too many manual steps!

What are your thoughts @SimenB @zbjornson?

[SimenB]

I think ideally we'd use semantic-release or something, which will tag, publish, create a GH release and (optionally) update a changelog file on every commit to master (we've got that set up in e.g. eslint-plugin-jest). This looks great in the meantime though!

[sam-github]

The only missing detail that is required in the current changelog is what kind of change it is (like a breaking change or a change in behaviour), in this version it is up to the contributors to put in the commit message. For me personally I don't see any problems with removing that information in the changelog.

Its implied by the version (breaking changes cause a major bump with semver), but I agree, the commit message should say whether it is a breaking change or not (I think it does

semantic-release also requires commit messages to lead with the change type. I've never used it, but it does look like a good match for this project.

I'm not sure if I have the time to set it up, but I definitely don't have the credentials. One of you would have to: https://github.com/semantic-release/semantic-release/blob/HEAD/docs/usage/getting-started.md#getting-started

Would you all like to get semantic-release running? If so, I'll close this (or leave it until semantic-release is running).

If not, I'll touch this up with maintainer notes so that the commit message format is clear to collabs, the keep-a-changelog refs are removed, and there are crib notes on the (one-line) shell command maintainers would be run to make a release. And if later you all move to semantic-release when you've time, no hard feelings, delete the strong-tools dep!

[zbjornson]

I'm late to the party, but I'm actually a -1 on automatic changelogs. Yes, the current changelog isn't much better than the auto changelog, but a manual changelog can be significantly better, including migration examples and longer explanations than what fits in the commit summary. (See https://github.com/Automattic/node-canvas/blob/master/CHANGELOG.md#200 for an example of another that I help maintain.)

I really like automatic linking to the commit or PR since commit messages are often useless, but it doesn't look like this PR does that, so it doesn't seem more useful than looking at GitHub's commit log IMO.

Since the current manual log is basically the same, I'll easily yield to your opinions, but again I like the flexibility of manual logs.

[sam-github]

a manual changelog can be significantly better

I don't disagree, but observation of https://github.com/siimon/prom-client/blob/master/CHANGELOG.md shows that this project is not doing manual writeups.

I really like automatic linking to the commit or PR

This does this: https://github.com/sam-github/prom-client/blob/try-generated-changelog/CHANGES.md (the #333 style PR links aren't showing up as hyperlinks because github is resolving them to github.com/sam-github/prom-client where they don't exist, once it merges, they will resolve to github.com/siimon/prom-client).

commit messages are often useless

That can be a problem, but its not clear how a manual changelog helps, since (right now) its written by the same person who wrote the commit message. If we can't convince contributors to write informative commit descriptions, I don't see how there is a better chance of getting them to write informative changelog entries.

So, in summary, while I agree that manual writeups could be better.... the maintainers here have opted to push the changelog writing responsibility to the PR authors, so they aren't better (and mostly are (manual!) copies of the commit description), and I don't see an appetite for, before every release, someone volunteering to do a nice writeup of the changes.

But that's just the view from here, I'm not doing the publishing. You all are!

[zbjornson]

(the #333 style PR links aren't showing up as hyperlinks because github is resolving them to github.com/sam-github/prom-client where they don't exist, once it merges, they will resolve to github.com/siimon/prom-client)

Is that definitely the case? From https://help.github.com/en/github/writing-on-github/autolinked-references-and-urls:

Autolinked references are not created in wikis or files in a repository.

That seems consistent with the Node.js changelog having to use markdown links (https://raw.githubusercontent.com/nodejs/node/master/doc/changelogs/CHANGELOG_V13.md), and the plain #xxx links in node-canvas not automatically converting (https://github.com/Automattic/node-canvas/blob/master/CHANGELOG.md).

---

I'll yield to y'all's opinion, but I'll also volunteer to maintain the manual change log (including rewriting entries to make them more helpful) if we go that route.

[sam-github]

Hm, yes, you are right, sorry! So the generation would have to be tweaked.

But lets let folks ponder how they want to do it. I like the semantic-release proposal. Maintaining prom-client isn't anyone's full-time job, easy maintenance (and good docs in the README, to avoid questions/issues, I've got some improvements there coming) seems a win to me.

[sam-github]

Any reason for me to keep this open? I can, but I'm cleaning up my open PRs, and if prom-client is likely to keep the status quo, or those with maintainer permissions are going to switch to semantic-release (I'd definitely support that), then maybe time to close it?