More unhelpful update descriptions

[Jamie Nguyen]

On 30/06/13 03:15, Adam Williamson wrote:
> On 2013-06-29 14:20, Till Maas wrote:
>> On Sat, Jun 29, 2013 at 01:07:29PM -0700, Adam Williamson wrote:
>>
>>> The upstream, RPM or git changelog is never a good update description.
>>>
>>> An update description should be a very clear high-level description
>>> of what the update does. The audience is a normal end-user who has
>>> 300 updates to apply and wants to know what they do. This person is
>>> not going to spend six hours reading changelogs.
>>>
>>> "This update simply fixes the bugs listed" is an okay description -
>>> it tells the reader what they need to know and re-assures them that
>>> the update doesn't do anything *else*. Of course, if it does, you
>>> need to explain that: "This update includes a new upstream release
>>> which fixes the bugs listed. You can find other changes in the
>>> upstream description at http://www.blahblah.foo".
>>
>> For this update description, no human intervention is required, because
>> it can be created automatically. If the person reading the notice wants
>> to know what the update does, there is no way around reading changelogs,
>> because they contain this information. If he or she just wants some
>> comforting words, then the GUI or update framework can generate them
>> just automatically.
> 
> I was intentionally covering two of the simplest kinds of updates, for a
> *lazy* maintainer. I'd consider those bare minimums.
> 
>>> I can't personally conceive of a case in which it would make sense
>>> to simply have some kind of changelog as the update description.
>>> That is not what the description is for.
>>
>> I only read update changelogs if I want to provide karma and am
>> wondering if there is anything special that I should test, therefore I
>> do not see any value at all in the update description. Maybe more
>> examples of good update description would help.
> 
> Here's the kind of update descriptions I usually write. I don't know if
> anyone *else* considers them good, of course :)
> 
> https://admin.fedoraproject.org/updates/FEDORA-2013-11724/liveusb-creator-3.11.8-3.fc19
> : "This update adds a dependency on usermode-gtk to make the application
> launch correctly from system menus."
> 
> https://admin.fedoraproject.org/updates/FEDORA-2013-11688/bijiben-3.8.3-1.fc19
> : "This update gives Bijiben an icon which is more clearly related to
> its function, and makes its name in the menu system simply 'Notes',
> which again makes its function much clearer."
> 
> https://admin.fedoraproject.org/updates/FEDORA-2013-11530/congruity-17-2.fc19,concordance-1.0-1.fc19,libconcord-1.0-2.fc19
> : "This update provides the latest versions of the libconcord,
> concordance and congruity packages that together provide support for
> Logitech Harmony remote controls. This update fixes many bugs and
> provides support for many remotes introduced in the last few years. The
> congruity package now includes an 'mhgui' tool for configuring remotes
> that only work through the new Silverlight-based myharmony.com site."
> 
> https://admin.fedoraproject.org/updates/FEDORA-2013-11463/fedora-release-19-2
> : "This update applies all the usual changes when going from pre-release
> to release: updates-testing repository is disabled, repo metadata is set
> to expire after seven days, etc. It is required for the final release of
> Fedora 19."
> 
> https://admin.fedoraproject.org/updates/FEDORA-2013-11265/roundcubemail-0.9.2-1.fc19
> : "This update provides the latest upstream version of roundcube, a
> minor release with various bug fixes. It appears to require no database
> or configuration update from version 0.9.0, should simply be a drop-in.
> See http://trac.roundcube.net/wiki/Changelog for the full changelog.
> Note that the License field on the package has been updated to be more
> accurate: see
> https://lists.fedoraproject.org/pipermail/devel/2013-June/184197.html
> for full details."
> 
> https://admin.fedoraproject.org/updates/FEDORA-2013-10293/system-config-keyboard-1.3.1-14.fc19
> : "With many thanks to Vratislav Podzimek, who wrote the fix, this
> update fixes system-config-keyboard to read and write the keyboard
> layout configuration via systemd-localed - and so makes it actually work
> again. Previously, it would set the layout for the current X session but
> it would not write the configuration correctly, so the change would not
> survive a reboot.
> 
> Note that system-config-keyboard reads and sets the system-wide keyboard
> layout. If you are using GNOME, your user session has its own keyboard
> layout configuration that overrides the system-wide configuration and
> can be set through the GNOME control center. If you are using KDE, you
> can choose to either use the system-wide configuration or use a
> KDE-specific configuration in the control center."

Adam, I've been trying to put more time into improving my own update
messages, so thanks for these examples!

It's important to put yourself in the shoes of the user. Does the user
have enough information to:
1) determine the nature of the changes?
2) determine how major the changes are?
3) make a relatively informed decision about whether to update?

For many of my previous updates, the message was just "update to
upstream release 1.2.3", which the user can't use to answer any of the
above questions.

All of your update messages above seem to satisfy this criteria, so in
my eyes they look good :-)


Kind regards,

-- 
Jamie Nguyen