More unhelpful update descriptions

Adam Williamson awilliam at redhat.com
Sun Jun 30 02:15:46 UTC 2013


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 Williamson
Fedora QA Community Monkey
IRC: adamw | Twitter: AdamW_Fedora | identi.ca: adamwfedora
http://www.happyassassin.net


More information about the devel mailing list