Draft: simple update description guidelines

[Kevin Kofler]

Rahul Sundaram wrote:
> The following are a set of simple guidelines for the update descriptions
> via bodhi (which is used by PackageKit to inform users of what has
> changed). These guidelines are intended to help end users understand the
> nature of changes in the update better. Bodhi is not used in rawhide, so
> these guidelines are not applicable for rawhide updates. Note that this
> is not connected to the rpm changelog.

These look good, I agree with the need for guidelines here.

> * All Updates must refer to a upstream changelog or equivalent if one
> exists. Otherwise a brief description (a couple of sentence at most)
> justifying the need for an update must be provided by the maintainers
> pushing the update.

I think this should not be "Otherwise". There should normally be BOTH,
unless the reason for the update push is clear to everyone reading the
upstream changelog. And if there's no upstream changelog, the package
maintainer should try to summarize the changes.

I'd suggest something like this:
* All updates MUST contain a rationale justifying the need for an update.
They SHOULD contain a summary of the changes in the new version or a link
to such a summary. Where upstream provides such a summary, it MUST be
linked to or quoted (linking is preferred unless it is short). The summary
SHOULD be in a format comprehensible at least by an advanced user, not a
file-level or even function-level changelog as found in some projects. In
some cases, the summary of the changes also doubles as a rationale (e.g.
for a security fix or some other critical bugfix). In all other cases, both
are expected.

Notice the use of all-caps "MUST" to make it clear it is mandatory. We've
been tolerating updates with blank or useless details for way too long.

> * If there are downstream bugs being fixed or intended to be fixed with
> an update, it must be referred within the update. Maintainers can choose
> to let bodhi auto close bugs or close it manually as well.
> 
> * For security update, add CVE information, if one exists.

+1 (to both).

> * It is highly recommended that package maaintainers highlight major new
> features, critical bug fixes or anything else that has a potential high
> impact on consumers of your update.

+1, should be obvious, but unfortunately it isn't to everyone.

        Kevin Kofler