Tooling

Changelog Generation

ASWF projects are encouraged to publish a change log with every release. Tooling such as git-cliff leverages metadata added to git commits using the Conventional Commits specification to help automate the process of changelog generation, or at least provide a starting point.

OpenImageIO currently uses git-cliff in their release process:

I have been experimenting with this for OIIO and OSL for the past several months. I'm just doing it myself, I was planning to eventually fully document the process (including committing to the repo the cliff.toml file I've cobbled together) once I was happy with it, but I haven't done so yet. Basically, the process for me is:

Start the first line of each commit with fix: feat: refactor: docs:, etc. the usual they suggest in conventional commits, plus a few variants of my own that I find useful.
For other people's PRs, I tend to edit their commit messages slightly for clarity when I do the merge anyway, so I also make sure to add this convention to their message. But if I don't catch 100% and make them CC, it's also no big deal.
I've edited a cliff.toml file that mostly does what I want.
When it's release time, I run git cliff to generate the first draft of release notes. But I edit it very heavily, I don't find the direct output useful except as a starting point.

I've found this really useful for my monthly patch releases. I can start with its output, rearrange the lines to rank the entries not just by categories but by importance to users, lightly edit the text (sometimes the first line of the commit buries the lede, from the user's perspective), eliminate the entires for commits that are of no interest to users and just clutter the release notes. (I'm not sure that release notes need to list a change that fixes typos in a comment, or that fix GHA CI esoterica that users won't encounter).

Maybe it gets me to the 80% point for those monthly releases that have always been close to one-line bullet points. I really like how git cliff can be coaxed into including a web link to the PR for each bullet item, and I also have it rigged to credit the author, when it's not me.

For the big annual release, maybe it only gets me 30-40% of the way there, because I really like many major features to have a more extended explanation that needs to be written by hand and rarely corresponds exactly to the first n lines of the commit messages. It's easy for reliance on git cliff to give you very cursory release notes that don't emphasize the right things. Again, I just use it as a starting point to get me a first draft that lists all the commits, each one annotated with a link to its PR and an author credit, roughly sorted into main categories, but then I will spend at least a couple hours (for a major release) hand crafting the actual release notes from that.

I think the quality of my release notes is somewhat lower than before I started using git cliff. It's easy to convince yourself to be happy with what you get with 5 minutes of git cliff than to spend 30-60 minutes that I would to make it by hand but 20% better. OTOH, I think the formatting is nice and I love that it gets populated with authors and links without my having to do that tedious work (so tedious that I never attempted it when I wrote all the release notes by hand). Like all things, it's a tradeoff.

One reason I edit so heavily for the annual releases is that I want the release notes to tell the "story" of the release in a clear way that makes people understand the main points of the release in the same way that I do. No automated system does that well. But it can be a starting point to just get it all down in a document and you take over from there.

You can see the results in OIIO's release notes. The patch releases (2.5.12.0) are very lightly edited versions of what I can coax git cliff into making. The major releases you can see are heavily rewritten to be more "in my voice" and explanatory rather than regurgitating the first line of the commit message.