I believe a good product needs clear and thorough documentation. I think shipping a quality product requires you to provide detailed and informative release notes. I try to live up to this in the curl project, and this is how we do it.

Scripts are your friends

Some of the scripts I use to maintain the RELEASE NOTES and the associated documentation.

maketgz

A foundational script to make things work smoothly is the single invoke script that puts a release tarball together from what is currently in the file system. We can run this in a cronjob and easily generate daily snapshots that look exactly like a release would look like if we had done one at that point. Our script for this purpose is called maketgz. We have a containerized version of that, which runs in a specific docker setup and we called that dmaketgz. This version of the script builds a fully reproducible release tarball.

If you want to verify that all the contents of a release tarball only originate from the git repository and the associated release tools, we provide a script for that purpose: verify-release.

release-notes.pl

An important documentation for each release is of course the RELEASE-NOTES file that details exactly what changes and fixes that have been done since the previous release. It also gives proper credit to all the people that were involved and helped making the release this particular way.

We use a quite simple git commit message standard for curl. It details how the first line should be constructed and how to specify meta-data in the message. Sticking to this message format allows us to write scripts and do automation around the git history.

When I invoke the release-notes.pl script, it performs a git log command that lists all changes done in the repository since the previous commit of the RELEASE-NOTES files with the commit message “synced”. Those changes are then parsed: the first line is used as a release notes entry and issue tracker references within the message are used for linking the changes to allow users to track their origins.

The script cannot itself actually know if a commit is a change, a bugfix or something else, so after it has been invoked I have to go over the updated release notes file manually. I check the newly added entries and I remove the ones that are irrelevant and I move the lines referring to changes to the changes list.

I then run release-notes.pl cleanup, which cleans up the release notes file – it sorts the bugfixes list alphabetically and removes pending orphaned references no longer used (for previously listed entries that were deleted in the process mentioned above).

contributors.sh

When invoked, this script extracts all contributors to the project since the most recent release (tag). Commit authors, committers and everyone given credit in all commit messages done since. Also all committers and authors in the web repository over the same period. It also takes the existing names mentioned in the existing RELEASE NOTES file.

It cleans up the names, runs them through the THANKS-filter and then outputs each unique name in a convenient way and format suitable for easy copy and paste into RELEASE-NOTES.

delta

The delta script outputs data and counters about the current state of the repository compared to the most recent release.

Invoking the script in a terminal shows something like this:

= Since curl-8_12_1 Feb 13 08:18:33 2025 +0100 =
Elapsed time:       10.4 days (total 9837 / 10331)
Commits:            122 (total 34405)
Commit authors:     14, 1 new (total 1343)
Contributors:       19, 8 new (total 3351)
New public functions: 0 (total 96)
New curl_easy_setopt() options: 0 (total 306)
New command line options: 0 (total 267)
Changes logged:      0
Bugfixes logged:     67 (6.44 per day)
Added files:         10 (total 4058)
Deleted files:       2 (delta: 8)
Files changed:       328 (8.08%)
Lines inserted:      7798
Lines deleted:       6318 (delta: 1480)

With this output, I can update the counters at the top of the RELEASE NOTES file.

I then commit the RELEASE-NOTES files with the commit message “RELEASE-NOTES: synced” so that the automation knows exactly when it was last updated.

As a courtesy to curious users and developers, we always keep an updated version of the current in progress release notes document on the curl website: https://curl.se/dev/release-notes.html.

Repetition

In my ~/.gitconfig file I have a useful alias that helps me:

[alias]
    latest = log @^{/RELEASE-NOTES:.synced}..

This lets me easily list all changes done in the repository since I last updated the release notes file. I often list them like this:

git latest --oneline

As this then lists all the commits as one line per commit. If the list is large enough, maybe 20-30 lines or something and there has been at least a few days since the previous update, I might update the release notes.

Whenever there is a curl release, I also make sure the release notes notes document is fully updated and properly synced for that.