PROJ: Automatically Generate a CHANGELOG.md per repo

[decause-gov]

Mentor Name

@decause-gov

Project Brief Description

https://keepachangelog.com/en/1.0.0/#how

Based on the expert guidance contained here, we can advise projects to use a verbose commit-naming scheme based on the suggested keywords here, and then create a github action that will scrape the git logs for mentions of those words, to generate a draft CHANGELOG.md file.

This would also require that CONTRIBUTORS adhere to guidance about using the special KeepAChangelog Prefixes in their commit logs, so, adding a section to CONTRIBUTING.md file would need to be paired with this action.

Scoping

2 weeks or less

Required

• GitHub Action Added to our DSACMS Org for others to copy
• update .github/CONTRIBUTORS.md to add guidance around using the KeepAChangelog keywords in commit headers.

Desired Date Window: (June, July, August, Any)

June

[decause-gov]

@jasonpatrickellykrause brought up a good point today about squash commits, so here's the theory:

• You can do squash commit, but then pipe the original commit messages as additional '-m' updates, so that you have preserved extended commit messages in a description format. See: https://haydar-ai.medium.com/learning-how-to-git-creating-a-longer-commit-message-16ca32746c3a

[Gaelan]

Worth noting that the site you link (https://keepachangelog.com) strongly favors manually-maintained changelogs over something generated from the commit history:

Can changelogs be bad?

Yes. Here are a few ways they can be less than useful.

Commit log diffs

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

I'm inclined to agree. We could probably get 80% of the way there with some sort of magic syntax in the commit messages to control changelog output, but that gets tricky fast. If we ever mess up the syntax, or just decide a changelog message can be worded better (and this is user-facing, so we want it to be worded well), we'd need a way to edit changelog messages, which is trivial if it's just a human-written markdown file but much trickier if it's generated from commits (without rewriting history in a public repo).

One possibility that seems sensible to me is some sort of GHA thing that checks for PRs that don't touch CHANGELOG.md, and replies with a comment saying something like "this doesn't have a changelog entry; unless it's a trivial change, it should probably have one".

[decause-gov]

@Gaelan agreed! We'd prefer that a human-maintained CHANGELOG.md would be preferable to a machine-generated. In cases where CHANGELOG.md does not exist at all, I think it would be better to have something than nothing (so long as it's not just a noisy copy-pasta that you can just get from git log ;)

Moving along a spectrum of maturity, you can imagine how we can provide guidance to go from zero to something to better to best :)

[Gaelan]

Fair enough. The messaging of "we provide this tool, but ideally you shouldn't use it" is a little hard to get right, but probably doable.

Speaking of which, is there an existing place for open-source best practice guidance at CMS? If not, starting one should probably be one of our first tasks :)

[decause-gov]

https://github.com/dsacms/ospo-guide is still very early stages, but we're working on consolidating our guidance ;)