Changelog: what are the meaningful units?

Just one more note about the changelog for now. As I’m playing around with it, more is becoming clear. Particularly regarding how to group the changes for presentation in the feed.

I should be intentional about the commits I make in the output repo. Each commit should contain a meaningful, related set of changes. A release may contain multiple commits.

Preparing a release message starts with a git log query:

git log --name-status LATEST_RELEASE_TAG...` query.

So the ‘objects’ in a release are the commits, with the commit message and a list of files added, modified or deleted.

A release ends with the creation of a new file under /changelog/, named for the release tag/date, listing all the commits.

A fictitious example

So what will people see in their feed reader?

An entry with a bunch of sections for each commit. The titles are the commit dates and message summary, followed by the commit message body, and then a list of files changed.

Perhaps like the following. This example contains a ‘new article’ commit, and a ‘miscellaneous edits to a series’ commit.

Release 24v1-1 – 2024-10-14

(Some change details are not shown for readability. Click on the titles to view the original commit in the git repository)

2024-10-10: new article in series ‘Understanding Git’

Here’s the latest installment in the ‘Understanding Git’ series: Advanced Log Queries. We dive into the details of finding useful information in your git history.

• Added: Understanding Git: Advanced Log Queries

2024-10-10: Updates to ‘Tiny House’ series images and text

I’ve made a few readability edits to articles in the ‘Tiny House’ series. I’ve also replaced a few of the illustrations with improved versions.

• Minor textual edits: Tiny House design tips
• Improved illustrations:
  • Tiny House Design Tips
  • Special Considerations for Drafting Plans for Tiny Houses

Writing a changelog like this, it should be noted, is editorial work. The first entry with a new article could be a verbatim copy of the commit message and the git diff output: one file added. The second entry, however, would probably have had a whole list of Added, Deleted, Modified files, including images. Here, I’ve demonstrated how I might edit that to make things more readable. The note at the top also draws attention to this fact.

This needs further editing to add personality

As I examine my changelog so far, I see that I can move even further from a ‘commit log’-like view. I don’t need the dates in the entries, and I can edit the text and changes list heavily to make it into much more of a flowing text. This is what people will be getting in their inbox, it needs to be written in my voice, not the computer’s!

One more thing: can this be filtered?

I’m thinking about a future use case where people could subscribe to filtered feeds of just series/topics/paths they’re interested in. I wonder if I can make the ‘commits’ into items in their own right. As it stands, a filtered feed could show just the releases which contain changes to paths specified in the filter. For example, someone interested in tiny houses might not want to get any updates about the Understanding Git series. But could we also then show them only the entries from that release which are about tiny house design? Maybe collapse the other ones? Lots of exciting terrain to explore yet!