Updates lacking descriptions

[Peter Gordon]

Ben Boeckel wrote:
> Updates need to be more descriptive than this. Changelog entries
> and CVS commits can range from "split package" to "oops, forgot
> the patch" to "attempted before newRepo finished, bump release".
> These are useless as update texts. Maintainers should list
> things that have changed (features added, upstream bugs fixed,
> etc.). Linking the upstream changelog or release announcement is
> also good.
> 
> If this is enforced (and it may be good to add it to the
> critical-path suggestion), updates will be reduced since when
> there's little to write about, there's less justification for an
> update in the first place.

I agree wholeheartedly. Without following the upstream release
announcements closely, a simple "Update to new upstream release X.Y.Z"
means _nothing_ to users. We should want people to know what changed, at
least briefly, with the updated version. What does the new release
bring? Does it fix any security or other major bugs? Is it still
compatible? I always ask myself these four main questions when creating
an update notice through Bodhi:

1. Does this package fix any security issues?

These should *always* be mentioned, with some unique and reputable
identifier for it (e.g., a CVE number, Fedora/upstream bugzilla report,
etc.). From my experiences, this is the only true requirement of Bodhi
of these four, since it's necessary for the security team's approval of
the update push request. 

2. Does this package fix any "show stopper" bugs?

Users should be told when the update fixes issues like crashers or data
corruption, which significantly reduce (or worse, eliminate) the
package's usefulness. 

3. Does this update bring any cool new features to users?

I feel it important to note any major feature additions that would
entice users to the update. Among a possible myriad of such changes,
perhaps it supports a new and better file format (e.g.,an office program
having ODF support added), or updated translations, etc.?

4. Lastly, Will this cause any expected or known incompatibilities
(backward OR forward) for the user? Would they need to recreate/adapt
their existing configuration? 

Okay, so this last one is actually two questions, but the point remains:
it is sometimes necessary to cause an incompatibility that can not (or
perhaps should not¹) be prevented. Hopefully, such a change can be
mitigated automagically (perhaps with some sed/awk-fu in the %post
scriptlet or similar); but this is not always the case (especially if
it's within the users' $HOME directories). Also, regardless of whether
or not such an automatic change is done, the user SHOULD be informed
about it. At best,  they would then know *why* their configuration
file(s) changed; and at worst, they would know to effect the change(s)
themselves. In short: I think it's very reasonable for users to expect
that new updates will work with their existing setups without
modifications, and it's similarly reasonable to expect a big fat warning
of some sort when this is not the case.

[1] For example, if there is a major security bug caused by how the
configuration is stored, and fixing it would change the format, then the
decision is between breaking compatibility or keeping the program
insecure: one that must be made for the former, much to users' potential
frustration.

With my updates, I try to always give a brief summary of what I think
are the most important and/or most visible changes - answering these
four questions - along with a mention on how to view the upstream
changelog for it, so they can know everything that changed, and not just
what the update mentions.
-- 
Peter Gordon (codergeek42) <peter at thecodergeek.com>
-------------- 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/20090812/cae75811/attachment.bin