I’ve been talking to various people about the update descriptions we show to the user. Without exception, the messages we show to end users are really bad. For example, the overly-complex-but-not-actually-useful:
Or, the even more-to-the-point:
Update to 3.15.4
I’m guilty of both myself. Why is this? Typically this text is written an over-worked and under-paid packager doing updates to many applications and packages. Sometimes the packager might be the upstream maintainer, or at least involved in the project, but many times it’s just some random person that got fingered to maintain a particular package. This doesn’t make an awesome person to write beautiful prose and text that thousands of end users are going to read. It also doesn’t make sense to write the same beautiful prose again and again for every distribution out there.
So, what do we need? We need a person who probably wrote the code, or at least signed it off, who cares about the project and cares about the user experience. i.e. the upstream maintainer.
What I’m proposing is that we ask upstream maintainers to write the release information in a way that can be shown in the software center. NEWS files are not stanardized, and you don’t typically have a NEWS file for each application in your upstream tarball, so we need something else.
Suprise suprise, it’s AppStream to the rescue. AppStream has a <release> object that fits the bill almost completely; you can put upstream version information and long (optionally translated) formatted descriptions.
Of course, you don’t want to write both NEWS and the various appdata files at release time, as that just increased the workload of the overly-busy upstream maintainer. In this case we can use appstream-util appdata-to-news in the buildsystem and generate the former from the latter automatically. We’re outputting markdown for the NEWS file, which seems to be a fairly good approximation of what NEWS files actually look like at least for GNOME.
For a real-world example, see the GNOME MultiWriter example commit that uses this.
There are several problems with this approach. One is that the translators might have to translate lots more text; and the obvious solution to that seems to be to only mark strings to be translated for stable versions. Alas, projects like GNOME don’t allow any new strings in stable versions, so we’ll either have to come up with an except for release notes ammendment to that, or just say that all the release notes are only ever available in C locale.
The huge thing to take away from this blog, if you are intending to use this new feature is that update descriptions have to be understandable by end users. Various bug fixes is not helpful, but Fixes a crash when adding a joystick is. End users neither care or understand Use libgusb rather than libusbx and technical details that do not affect the UI or UX of the application should be omitted.
This doesn’t work for distribution releases, e.g. 3.14.1-1 to 3.14.1-2, but typically these are not huge changes that we need to show so prominently to the user.
I’m also writing a news-to-appdata.py script, so if anyone wants to take the plunge on an existing project it might be good to wait for that unless you like lots of copy and pasting.
Comments, as always, welcome.
Most updates is a very techical by nature and trying to translate them to non technical users is a little awkward, because the target audiance for these update changelogs is not the non techical user and is not ment to be.
If you install the foo application, you only need to know what the foo application does and when an update is available, the non tech users just need to know there is an update to foo. If the user need to know more about foo, then the user can read the appdata description or go to the upstream website.
On mayor updates the upstream should proberly update the appdata description with new mayor feature or at least update the application website.
I don’t think I entirely agree. For a start, I think this:
“Without exception, the messages we show to end users are really bad.”
was unnecessarily broad. I work quite hard to write useful and informative update descriptions, and I think there are other packagers who do too. *Some* packagers don’t, but please don’t tar everyone with the same brush.
For the broader point – well, I guess my biggest problem is this handwave:
“This doesn’t work for distribution releases, e.g. 3.14.1-1 to 3.14.1-2, but typically these are not huge changes that we need to show so prominently to the user.”
Well, no, I can’t go with that. Distribution changes frequently *are* significant to the user, I mean, in the end it’s all ‘for the user’. I think a mechanism by which this style of change log could be provided upstream for distributions to consume downstream would be a useful and handy thing, but I don’t think it would be safe to expect that it could simply replace distribution-specific notes. It should always be easy for the downstream packager to supplement or replace the upstream update text.
What about a list of URLs pointing to release announcements (blog post, ML post, forum post etc.) with a link display title. This would allow upstream to decide how they want to present their changes e.g. include images, screencasts, links to the bug tracker or related discussions.
Which tags are supported inside description? I fear a complete HTML support that would allow upstreams to do weird things like downloading images from owned server for tracking users, but would of course love having links, advanced markup, and things like that…
You’re just allowed to use p, ul, ol and li :)