Could we have better guidelines around package changelogs?

As a user of Fedora, when I update applications I would like to know what has changed. Some applications are fairly good at this, for example zenity, however the vast majority that I’ve looked at have absolutely useless changlogs on them.

“Updated to X version” tells me nothing about what has actually changed in the package.



I have no idea where to start the discussion on this, but I figured this might be a good place. What would the process for proposing some guidelines around what a good changelog for a package is?

For example, Firefox 113.0 has the following changes that are applicable to its Linux version:

  • Enhanced picture-in-picture functionality
  • Enhanced functionality to searching in the address bar
  • Private windows now block third party cookies by default
  • Passwords generated by Firefox now include special characters
  • Improvements to the accessibility engine
  • Improved AV1 and AVIF support
  • Firefox is now available in Tajik (tg) language
  • Various security fixes (see: MFSA2023-16)
  • Deprecated interfaces (mozRTCPeerConnection, mozRTCIceCandidate, and mozRTCSessionDescription) have been removed from WebRTC

The oversimplified “Updated to latest upstream (113.0)” doesn’t let the user know about any of that and this is just one package as an example. This issue with the lack of proper changelogs makes it very annoying to have to search up every package individually to check what has changed, and makes the update process less user friendly overall in my opinion.

Packaging Guidelines say:

The intent is to give the user a hint as to what changed in a package update without overwhelming them with the technical details. They must never simply contain an entire copy of the source CHANGELOG entries. Links to upstream NEWS files or changelogs can be entered for those who want additional information.

I doubt the package maintainer has time to always write up such a nice text as you did. But if there’s some upstream page that could be linked to, it’d be nice to put the link in the changelog. If %autochangelog is used, that link would go in the commit message.

2 Likes

What you’re seeing in these dialogs isn’t the package changelog, it’s the update description in Bodhi. For example for zenity-3.92.0-2.fc38 the most recent changelog entry is:

Backport two patches from upstream to hopefully really fix crashes (#2177287)

But the update description in Bodhi is:

This update backports a couple of fixes from upstream that I hope will really fix the crashes on launching Steam (etc.) this time.

In the Bodhi web interface the description field has this placeholder text before the user starts filling it in:

Update notes go here. Please be as descriptive as possible. Help testers know what to test, and users know why this update is available and what major changes it brings (if any).

It’s nice when maintainers take the time to fill out good descriptions for their updates, but this is hard to enforce beyond the recommendations we already have in the guidelines and the Bodhi placeholder text. Do you have any suggestions on how we can encourage more maintainers to take the time to do this right?

2 Likes

A link to the changelog would be helpful if you wanted to get more detail for specific changes, but I think that having a nice summary there as well would be a lot more user friendly.

Just having links there would lead to situations where you need to go between your web browser and GNOME Software many many times just to read them all.

Sorry, I didn’t realize these were two different fields, but I hope you understand what I mean. I’m not a package maintainer, nor do I really use Bodhi other than to check if an update fixes a bug I’ve reported.

As for suggestions, I think having a minimum requirement to at least write a sentence for what users can expect to see in the update would be nice (not just “Updated to X version”). I don’t know the optimal amount of detail to go into in the changelogs, but I think the bullet point list I gave above for Firefox 113 would be a good starting point. It doesn’t copy word-for-word the changelog from there, but it does at least give the user an idea of what has changed.

At the very least having a requirement to highlight security fixes would be great. When a package has a security fix as part of the update I will usually prioritize updating those and making sure all my systems have that security fix in place. New features and bug fixes are a bit harder, since there might be quite a lot of them in an update, but at least giving a couple of the larger features or high severity bug fixes would be nice.

I have no idea how best to incentivize package maintainers to do this. However I think updating the guidelines to be a bit more specific on what is and is not a good changelog would be nice, then work from there to see why the majority of maintainers don’t see this documentation as important would be a good place to start. Perhaps a poll for maintainers to see what their biggest problems with this process is would be helpful? If there are specific things that take too long, or are blockers for why they can’t then those issues could be addressed.

The guidelines already state that if an update resolves a CVE, that CVE number should be mentioned in the changelog (and logically this would extend to the Bodhi update, which can also be explicitly marked as a security update).

The package update guide also goes into detail about filling out the update description, which sounds similar to what you’ve described here.

I’ll also note that these documentation pages are open source and accept pull requests if you have ideas about improving them. Look for the pencil icon in the upper right.

All that being true, the packager’s perspective might be that we focused on the spec changelog (which ends up in the rpm) and dist-git log mostly, and autochangelog adressed the issue that packagers often used one of these logs only. Now, we can specify information in dist-git-log in a way which (selectively) populates the rpm changelog, too. The latter was supposed to be “user facing”, the former “packager/technical”.

I think we forgot about bodhi while doing that. It does not help that - depending an what type of user we talk about - they will look at the rpm changelog or the bodhi update comment. Maybe we should teach bodhi to suggest accumulated changelog entries (since the last update) to the packager in the update template?

Actually there’s something like 4…

  1. The git commit history for the package
  2. The %changelog in the package
  3. The bodhi update comments
  4. The upstream NEWS/Changelog/WHATS-NEW/Release announcement

1 and 2 are often the same or similar and indeed are identical on newer
packages (because there’s no changelog in the package, only git
commits).

and

Those guidelines have:

"
The intent is to give the user a hint as to what changed in a package update without overwhelming them with the technical details. They must never simply contain an entire copy of the source CHANGELOG entries. Links to upstream NEWS files or changelogs can be entered for those who want additional information.
"

Perhaps we could adjust the bodhi form to provide more info for
maintainers, I think thats probibly the best area to improve.

Thanks for the topic…

1 Like

I mostly push my updates using fedpkg update. While that allows for a
multi line --notes, I find it awkward to use.

However, populating the notes from the changelog entries instead,
similar to how Bodhi determines which bugs to update, sounds like an
improvement.

Putting a link to the upstream changelog[1] in the commit message
sounds like a good idea. Perhaps that could even be parsed into the
notes as long as it is structured?

I use towncrier[2] for one of my packages and find it very useful for
taking the burden of handwriting a changelog file off my shoulders. It
requires discipline, though.


  1. provided upstream is good at maintaining a changelog ↩︎

  2. GitHub - twisted/towncrier: Manage the release notes for your project. ↩︎

I suggested a while ago that we have some special syntax for the git changelog marking text to be automatically used for the bodhi update. People weren’t too keen on that, though.

I also think that “upstream changelog URL” would be a useful bit of RPM header metadata.

1 Like

I general, I think trying to convince (or force) packagers to spend more time writing better changelogs is the wrong approach. We should strive reduce the amount of time that goes to an individual package upgrade. A solution that produces a passable result with less work is preferable to one that produces great results with more work.

Since changelogs are already being written to various places upstream and in Fedora, I say automatically copying them around is the right solution. And since there is endless variety in upstream changelogs, automatically processing them is not going to be easy. What remains is using something produced within Fedora.

Rpmautospec already chose the Git changelog as the source of truth, so the sensible way forward is to use that. Either directly, or indirectly by reading the package changelog that is generated from that.

Right, that does not appeal me, because then I would be in a situation where I have a free text field in whatever editor I use to fill the Git changelog, plus some increasingly complicated syntax I need to use to get the content processed correctly. Rpmautospec is already causing this problem a bit, but luckily its special syntax is still quite simple.

However, just automatically pushing the package changelog to Bodhi update is different. That does not require me to consider anything extra, and it reduces the manual work I have to do as a packager. I think that would be a great improvement. For people who like to, or have to, manually craft Bodhi changelogs, the option to edit it after the initial fill could be left available.

3 Likes