Release Engineering on Brian Faust

From Commit to Changelog: An Intent-Aware Release Pipeline

Fri, 01 Aug 2025 00:00:00 +0000

Most release processes postpone the important questions.

A developer commits a change. A pull request describes some of it. Somebody adds a changeset because CI demands a file. Much later, another person opens an Unreleased section and tries to reconstruct what users need to know.

The tools are connected by chronology, but not by meaning.

That is why release day becomes an archaeological exercise. The diff still exists, but the reason, audience, migration path, affected application, and release judgment have been scattered across Git, an issue tracker, review comments, and somebody’s memory.

Unreleased Is Not a Junk Drawer

Tue, 01 Jul 2025 00:00:00 +0000

Keep a Changelog got one foundational idea exactly right: a changelog is for people. It should explain noteworthy changes instead of dumping commit history into a Markdown file.

That principle is sound. The document model built around it is where the frustration begins.

The problem becomes most visible under this heading:

## Unreleased

The failure mode is easy to recognize. Everything remotely noteworthy goes there while work is in progress. When a release approaches, somebody finally decides which application the entries belong to, rewrites their summaries, moves them under categories, removes internal noise, adds migration notes, and tries to reconstruct why half of the changes mattered.

A Pull Request Is a Review Narrative, Not a Template

Sun, 01 Jun 2025 00:00:00 +0000

Most pull-request templates start with good intentions and end as paperwork.

They ask for a summary, testing instructions, screenshots, a ticket, a risk assessment, a deployment plan, a rollback plan, and twelve checkboxes. A small change answers half of them with “not applicable.” A large change fills them with links. The template is complete, yet the reviewer still has to reverse engineer the actual decision from the diff.

The failure is not Markdown. It is treating the presence of headings as proof that communication happened.

Intent Commits: Commit Types Are Not Release Decisions

Thu, 01 May 2025 00:00:00 +0000

Conventional Commits solved a real problem. It gave teams a small shared grammar for a part of software development that had mostly been left to taste:

feat(auth): support passkeys

That line is easy to write, easy to scan, and easy to parse. It is a much better foundation than histories full of changes, updates, and fix stuff. It can drive changelogs, release automation, and navigation through an unfamiliar codebase.