This is a suggestion I would like to make for the Nextcloud release team(s).
As a maintainer of multiple Nextcloud instances, the current format of changelogs is very inconvenient. Before deploying an update, I need to know what’s changed so that I can ensure everything works as expected after the update.
Because the changelog essentially consists of a list of commits, reviewing it is time-consuming and error-prone. I don’t need to see every individual commit: I can get that on GitHub. What I (and possibly others) need as a system administrator, is a curated description of the important changes in the release.
Using commit log diffs as changelogs is a bad idea: they’re full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.
The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don’t.
The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.
Hopefully this suggestion can lead to some discussion and improvement around the issue of providing useful changelogs.
Thanks for sharing your suggestion @lavamind. Making the changelog easier to digest wouldn’t hurt, and I’ll bring it up to the team to see how we can improve it.
In the meantime, one other thing we do is a blog post for the releases and an email announcement. We summarize changes in those, so it’s not a list of commits/PRs.
This is the latest one:
You can find the past release blog posts here:
And if you want to get an email, sign up here and check the release announcements:
Thanks taking the time to respond and for highlighting these blog posts! That’s definitely useful.
If we wanted to make the Changelog page more useful, my suggestion would be to reproduce the same content as the blog post in the form of a bullet point list under the Changes header, with a link to GitHub’s list of commits between the relevant tags below that.