[RFC] Package Updates/Bodhi Notification Content Policy?

[Peter Gordon]

Hi, all.

[I use X/Mesa stuff as an example only. Many other package updates
contain similar problems, and the X/Mesa stuff certainly isn't one of
the worst. Also, "notable changes" and similar phrasing in this message
hereafter refer to any major bug fixes (such as those which resolve
crashers or problems which cause loss of data), new enhancements (new
features or changed subpackages), security fixes, and the like.)]

Recently, there have been a slew of updates (especially X/Mesa related
packages, though not exclusively) that have no helpful message in their
update announcements. The last several %changelog entries are included,
thankfully; but even those often fail to describe the update properly.

I, for one, have not updated my system's mesa-related packages yet,
because the new release (-37 versus -35) seems to cause rather severe
performance issues. (FPS in Tremulous, for example, drops from a normal
45-55 to barely double-digit.) I can imagine a similar situation with
dial-up users or users with limited bandwidth, such as with pay-per-use
connections: Is the update useful enough to spend the time and/or money
in downloading?

The only notification in today's X updates, for example, is that it
contains a new RC5 snapshot (and that's from the package %changelog).
From the perspective of an end-user, I am thinking "What's changed?
What's fixed? Any cool new features? Will the packages fix my DRI/OpenGL
slowness?"

Noting a new version or snapshot is a good thing, sure; but users should
not need to go hunting through down upstream changelogs or bug trackers
or to figure out why the package update is being issued. 

I'd like to propose a short policy of sorts to ensure that users are
properly notified of notable changes.

1. Any such notable changes should be briefly described in the Bodhi
entry. Essentially, package maintainers should summarize the key points
of the upstream changelog for these.

2. Relevant bug numbers or IDs should always in the Bodhi entry, either
for Red Hat/Fedora bugs (in Bodhi's "bugs" field), or as bug numbers
from an unambiguous tracker (in the update comments). For example: "Fix
GNOME Bug 98765" is good; but "Fix b.g.o#98765" is bad, since that could
be (at least) bugs.gentoo.org, bugzilla.gnome.org, or even
bugs.gobolinux.org, et al.

Corollary: However, we don't want to be overly redundant in the notices.
If we already include a bug number in Bodhi's "bugs" field, and that
bug's title is descriptive enough, then it may very well be that simply
referencing that bug in the update will tell users what's fixed - since
Bodhi will automagically retrieve that and insert it into the
announcement. For example, if your update through Bodhi shows "bug
123456: App crashes: segfault when enabling option foo," then it is not
entirely necessary to note this fix in the update comments. Other
changes should still be mentioned (if any). Similarly, if the %changelog
includes a mention of these notable upstream changes, the update
comments do not need to also include them (since the %changelog entry is
also inserted as part of the update announcement).

3. Any and all attempted empty Bodhi updates with no bug references
should return an error message, telling the maintainer to add a brief
comment describing the change and/or referencing appropriate bugs (and
perhaps referencing this policy).

Simply being a new version is not always a good reason to update! On the
contrary, new versions often bring new bugs and potential regressions -
especially with snapshots of upstream sources instead of deemed-stable
release tarballs.

[Rawhide does not use Bodhi updates and is generally not intended to be
as stable as releases, so merely noting the version bump is OK in the
package %changelog, though I still recommend summarizing some of the
more important notable package changes.]

Thanks for your time!
-- 
Peter Gordon (codergeek42)
GnuPG Public Key ID: 0xFFC19479 / Fingerprint:
  DD68 A414 56BD 6368 D957 9666 4268 CB7A FFC1 9479
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/devel/attachments/20080723/e48fd18d/attachment.bin