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
--
devel mailing list
devel@lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/devel
