changelog bot

[yoshuawuyts]

I was thinking it might be useful to create a GH changelog bot. Whenever a GH release is pushed (e.g. npm tag) it'd look at all the commits that were part of it, and create a changelog as the body of the github release. This would make it easier to look at what changed between versions, credit contributors, and improve the overall quality of the project.

It'd be super neat if someone would be willing to take this on! Any ideas on how to further improve this / approach this would be very welcome!

Stuff that'd probably be good to list in a changelog

• links to all commits
  • link to corresponding PR
  • link to corresponding commit
  • link to who made a commit
• comment on all PRs that were merged into the release, linking to the release
• link to contributors that participated in making the patch possible (comments, merges, reviews, etc.)
• link to first time contributors that participated in making the patch possible
• time since last release

Stuff that probably shouldn't be part of these automated changelogs

• any human text 🤖 – long form patch notes, and introductions to features are probably best left to dedicated blog posts, introductions, or docs updates. Leaving the option out all together is probably

Stuff that'd be neat if we could pull off

• go back in time, and craft notes for all releases on the choojs org (automated, of course)

Final thoughts

Before closing this out, I thought it might be fun to create an example changelog of what I was thinking, for the latest Choo release. (Sorry in advance for the mentions, @silawrenc :P)

---

2017-09-09, Version 6.4.1

This release contains 1 commit, was released by @yoshuawuyts, and comes 3 days after the last release. Many people came together to create Choo v6.4.1. We couldn’t have done it without all of you. Thanks!

Commits

• [8595f1f] – Populate state.query before calling router (Simon Lawrence) #575

First Time Contributors

• Simon Lawrence (silawrenc) :tada:

Contributors

• Yoshua Wuyts (yoshuawuyts)

[jakeburden]

This looks verrrryyy cool. I wonder if something like sematic-release could be used as a starting point.

[yoshuawuyts]

Some more reference material:

• https://github.com/devtools-html/debugger.html/blob/master/docs/updates/updates-9-5-2017.md
• https://github.com/nodejs/node/releases/tag/v6.11.3

[ungoldman]

Here's some other prior art to consider:

Some folks believe a good change log is written, not generated:

• http://keepachangelog.com
• https://github.com/hypermodules/gh-release

Others believe change logs and releases can be fully automated by being methodical about git commits:

• https://github.com/conventional-changelog/standard-version
• https://conventionalcommits.org

For generating change logs and releases from git commits, I prefer standard-version to semantic-release, mainly because of semantic-release's decision to never update the version in package.json -- which to me means version history is inaccurate, and if in the future I switch to another release strategy, my package.json is broken.

I've used both of the methods above and find each to be adequate. One thing they both do is keep a change log file in git history. Though the releases page on github is useful and I understand the appeal of just using that instead of maintaining an actual change log file, I've found a file as the official record to be preferable. Github releases are a commercial platform feature independent of git, and they are not accessible by cloning the repo and would be lost if the platform dies. For the same reason that I think keeping version changes in git history is a good idea, I would say keeping change log in git history is a good idea.

[dpaez]

Hello everybody 👋

Just to add something to the conversation, at GEUT we made this CLI (it can be used programmatically too) based on the ideas behind keepachangelog, it's a tool called chan.

It primarily helps you to maintain a changelog and it can be extended using a plugins mechanism. You can check it out, maybe it helps. 👍