The Peril of Contractual Release Notes
Automated release notes are a common feature in software development, often generated directly from Git commit history. While efficient for summarizing changes, these notes frequently fall into a trap: they treat narrative bullets as contractual obligations for users performing upgrades. This can lead to significant user confusion and frustration when the implied promises of compatibility, data preservation, or supported command syntax are not met after a version bump.
The core issue lies in the nature of commit messages versus user-facing guarantees. Commit subjects describe the work that was completed, not necessarily the stable, supported interface that a user can depend on. A commit might detail the renaming of a flag, but it won't explicitly state whether the old flag spelling remains valid for backward compatibility post-upgrade. This ambiguity, when presented as a definitive statement in release notes, creates a false sense of confidence for users navigating software updates.
The problem isn't that models can't inventory commits, paths, or symbols. They can do this with high accuracy. The challenge is that these models cannot, by their nature, honestly promise a specific migration path or guarantee backward compatibility. The language required for such assurances is fundamentally different from the descriptive language of code commits. This workflow proposes a clear separation to maintain the integrity of both the factual record and user-facing promises.
A Mechanical Split for Clearer Communication
The proposed solution hinges on a mechanical, rather than stylistic, division of responsibilities. Instead of attempting to create a single, unified release note that serves both as a factual summary and a contractual agreement, the workflow splits these functions into two distinct files. This approach ensures that the factual inventory of changes and the explicit promises made to users are managed separately, preventing the latter from being smuggled into the former without proper vetting.
The first file is a facts file, compiled directly from the Git history and public symbols of the codebase. This file serves as an objective record of what changed, detailing commits, modified files, and altered symbols. It is the raw output, devoid of interpretation or forward-looking guarantees. Think of this file as the raw ingredients list for a recipe – it tells you what's in the dish, but not how to cook it or what it will taste like.
The second file is the reviewer contract. This is where all upgrade claims, compatibility assurances, data preservation guarantees, and statements about supported commands must reside. This file is owned by a human reviewer who is responsible for ensuring that any prose drafted from the facts file accurately reflects these contractual commitments. If a sentence in the release notes implies compatibility or data preservation, that implication must be explicitly backed by an entry in the reviewer contract.
Drafting Prose: Summarize, Don't Contract
With this separation, the process of drafting the human-readable release notes becomes more focused and less prone to error. The drafted prose can summarize the facts file, providing users with an understandable overview of the changes. However, a critical rule is enforced: if a sentence in the drafted prose implies compatibility, data preservation, or the continued support of a specific command, that statement must have a corresponding, explicit entry in the reviewer contract. This ensures that any user-facing promise is intentional, reviewed, and documented.
This model prevents the accidental smuggling of unsigned promises into the release notes. Commit messages, by their nature, describe the work that landed. They are not designed to be a binding agreement with users regarding the consequences of an upgrade. File churn, for instance, might look like a complete story in an automated changelog, but it never states whether a renamed flag still accepts the old spelling or if data migration is seamless. The reviewer contract addresses this by requiring explicit statements for such scenarios.
Implications for Development Workflows
Adopting this workflow has several key implications for development teams. Firstly, it enforces a higher standard of clarity and honesty in release notes, reducing the likelihood of user error during upgrades and fostering greater trust. Secondly, it creates a more robust auditing trail for release promises. The reviewer contract acts as a clear record of what the team committed to, making it easier to track and manage backward compatibility efforts.
For developers, this means a more deliberate approach to how changes are communicated. Commit messages should remain focused on the technical details of the work. However, when features or changes have user-facing implications that involve compatibility or migration, these must be explicitly documented and agreed upon in the reviewer contract. This encourages a more proactive approach to managing breaking changes and ensuring a smoother user experience.
The split also clarifies ownership. The automated process is responsible for the factual inventory of code changes. Human reviewers are responsible for the contractual promises made to users. This division of labor leverages the strengths of both automation and human judgment, leading to more reliable and trustworthy software releases. The goal is not to eliminate automated changelog generation, but to augment it with a critical human layer that uphns user expectations.