The Module Changelog Is Not the Git Log
One changelog row can summarize six commits: curated module logs beat raw git history.
TL;DR
Six commits landed in one day, but the module changelog captured the whole shift in a single row. Turns out git logs record the mechanical steps of how code was built, while a curated changelog states what the product now does. Automation can list commits, but it can't infer triggers or QA flags, so human judgment stays essential.
I opened the QA module changelog file at qa-reports/modules/service.md. It is a living document structured with four columns: Date, Change, Trigger, and QA re-run needed. On a recent Tuesday, this file summarized a massive behavior shift in exactly one row. Yet, the repository recorded six separate commits that same day.
My initial guess was that those six commits were merely board chores. I assumed they were issue moves, minor refactors, or noise commits not worth recording in a meaningful log. I thought the single changelog row was a dangerous oversimplification of the actual engineering work.
I was wrong. The changelog row existed precisely because those six commits consolidated a behavior-contract change into one meaningful unit. The git log shows the mechanical steps of how the code was assembled. The module changelog states what the product now does.
The Taxonomy of Change
The six commits covered distinct technical actions: freeing status transitions, adding a conditional reject note, updating the wizard to offer all statuses, and deleting an obsolete mockup route. In the git log, these appear as fragmented events. In the module changelog, they fall under a single classification.
According to Keep a Changelog, the Changed category is reserved for when a behavior worked as intended and now works differently [1]. This taxonomy forces us to group related mechanical commits under one user-facing reality, rather than fragmenting the narrative across half a dozen commit messages.
Semantic Versioning and Compatibility
A natural question arises: if the behavior changed so drastically, why was this not a breaking change? Semantic Versioning provides the answer [2]. The API endpoints and payload structures remained entirely untouched. Only the internal business rules shifted. Because the external contract held firm, the update did not require a major version bump, even though the user experience evolved significantly.
The Limits of Automation
Modern git hosts can automatically generate release notes starting from merged pull request lists [4]. While useful, these automated outputs still demand heavy human curation. They list the commits, but they cannot infer the "Trigger" or determine if a "QA re-run needed" flag should be set.
Projects that maintain rigorous standards, such as the Claude Code CHANGELOG [3], demonstrate that automated lists are merely a starting point. The principles outlined in Keep a Changelog 2.0.0 further emphasize that human judgment is required to translate technical commits into user-centric narratives [5].
I now treat the module changelog as the definitive source of truth for product behavior. The git log remains valuable for tracing the historical mechanics of the build, but it is the curated changelog row that tells us what actually matters to the user.