In my experience in other projects, adding a CHANGES.md is a lot of work, but it is a good time investment because it creates a comprehensive list of product features that can be understood without reading any code.
For example, in Calcite, we generate the list [1] from commit messages, most of which are the summary text of Jira cases. That in turn requires upstream work, crafting a really good single-line description of the case before it is fixed. As you say, that description needs to describe the problem in terms the user will understand. If the description is good, it is clear whether the case is a bug-fix or new feature. The list is automatically deployed to the site [2]. The release manager generates the list by piping ‘git log’ through a shell script to produce one line for each commit since the last release, then sorts the lines into sections ‘New features’, 'Bug-fixes, API changes and minor enhancements’, ‘Built and test suite’, ‘Dependency version upgrade’, ’Web site and documentation'. They remove some lines, e.g. when a commit is amended or backed out, and fix obvious typos. They manually add a description of the release and, if necessary, a ‘Breaking changes’ section. Creating user-friendly descriptions is hard work, regardless of who does it. In my opinion, it is unfair to put it all on the shoulders of an unpaid release manager; but if you leave it to contributors, you get poor-quality and inconsistent messages; so the best time to do it is as early as possible, namely when cases are logged/triaged. The rationale for this last option gets ever stronger. If a case has a good summary, and a description with one or two examples, AI can often write the code and tests automatically. Julian [1] https://github.com/apache/calcite/blob/main/site/_docs/history.md [2] https://calcite.apache.org/docs/history.html > On Jan 21, 2026, at 1:56 AM, Hans Van Akelyen <[email protected]> > wrote: > > Hi All, > > A small discussion to have where I would like your input is to add a file to > the root of the repository to highlight the most important changes for each > release. > Currently it is the work of the Release manager to sift through our tickets > and try to create a comprehensive list of the key changes for each release. > This causes useful changes to slip through the cracks... > > While we do always generate release notes in our GitHub releases I find that > list to be not too user friendly. It's often a bit too technical. > It usually also does not translate to a great starting point for the release > blog post. > > I see 2 paths we could follow. > > 1. Add a release notes or changes document to our repository (examples [1][2]) > 2. Put a bit more effort in making our PR messages more clear, as you can see > in our notes[3] a lot of those lines are either not user friendly or > technical things that the user doesn't care about. > > > > Let me know what you think, > > Cheers, > Hans > > [1] https://github.com/apache/beam/blob/master/CHANGES.md > [2] https://github.com/apache/airflow/blob/main/RELEASE_NOTES.rst > [3] https://github.com/apache/hop/releases/tag/2.16.0-rc1
