Use git cliff to generate changelogs

[max-sixty]

What's up?

The new version of git cliff supports GitHub handles. So we could use it to generate changelogs.

If anyone is up for a dev-ops PR, this would be great. The goal would be to generate something similar to our current changelog, using the prefix of our commits to group them (which git-cliff supports)

[richb-hanover]

@max-sixty I'm quite content with the current format and information contained in our current Changelog. Even though we have to manually curate the comments, they provide a good description of the project's progress.

My primary concern is that an automatically-generated file will hide the actual information in a flurry of commit messages. Could you point me to a sample git cliff changelog? (This project or some other project would be useful.) Thanks.

[max-sixty]

Definitely worth checking out some of the git cliff outputs and seeing what we thinks looks best. I am keen to reduce the burden of releasing as much as possible, so unless someone wants to own maintaining the changelog, automation should win out...

[richb-hanover]

In seeking a sample git-cliff output, I went to their repo:

Changelog: https://github.com/orhun/git-cliff/blob/main/CHANGELOG.md
Commit History: https://github.com/orhun/git-cliff/commits/main/

It's definitely a nicely formatted file. The Issue number and commit hash is useful. And if I squint, I can see how it lines up with the commit history.

I do wonder how fussy git-cliff is about the tagging and labeling of commits. Do we wind up trading a headache for an upset stomach? (Simplifying the creation of the Changelog while enforcing a bunch of strict rules for the commit messages?)

As for the current PRQL Changelog, I really like the narrative format. It helps the reader understand if it's a major release, a little one, just a bug-fix, etc. It also lets the reader get more context about what we're thinking.

And the current Changelog format allows people to make incremental entries that describe interesting changes they've made, while eliding the little stuff.

I suppose there's a hybrid path: retain the narrative form, while letting git-cliff generate the fussy PR/Issue/commit lines that can be inserted.

I'm not sure any of this helps make the decision. But thanks for listening.

[max-sixty]

I still think we can have a few lines at the top of each release. It's normally me doing the releases and I'm happy to do that.

The main thing it can automate is the listing of the changes — which no one seems to love doing...

[richb-hanover]

The main thing it can automate is the listing of the changes — which no one seems to love doing...

Oh, yeah. I totally agree that part is a pain. That's kind of what I was thinking when I suggested a hybrid model: hoover up the git-clif changes (maybe even curating those (how does it handle/minimize multiple commits that fix typos, etc?)) and fitting them into the narrative.

This still requires some hand-work, but automates the painful parts.

[snth]

Thank you for those links @richb-hanover .

I was going to ask if there is a way to display PR/Issue numbers rather than commit hashes and after a quick look around I see that it uses a templating engine (similar to Jinja2 syntax) and that should be easily configurable. In fact based on this snippet, you could easily do the opposite of that and only include only specific commits, PRs, etc...

Sounds good to me!

[richb-hanover]

In case it wasn't clear from my earlier note: Yes, let's try this. Thanks.