Draft: simple update description guidelines

[Mark McLoughlin]

On Wed, 2009-01-28 at 15:50 +0530, Rahul Sundaram wrote:
> Mark McLoughlin wrote:
> 
> > I'd suggest the tone should be less prescriptive - i.e. not so much "you
> > must do foo" - and also give some rationale.
> > 
> > e.g. "when preparing your update, consider what the user will see and
> > how they will decide whether they should apply the update".
> 
> I am probably not going to be very good at doing this. Do you want to try?

Okay, here's an attempt:

  https://fedoraproject.org/wiki/User:Markmc/Draft_package_update_guidelines

Cheers,
Mark.

= Package Update Guidelines =

This page is intended to give some guidelines relevant to package
maintainers who wish to update a package on a release branch.

These are not intended to be prescriptive rules. Package maintainers are
free to exercise their own common sense and good judgement.

== Maintaining Stability ==

Many Fedora users update automatically, so it is most important that an
update doesn't cause a users' applications or system to stop working
suddenly.

Bug fix updates should generally be first pushed to testing and only
pushed to stable after it has achieved sufficient karma in bodhi.

New upstream releases should not necessarily be pushed to release
branches. The benefit of the bugfixes and new features should be weighed
up against the risk of regressions. A simple rule of thumb might be to
not push the new release unless it fixes a problem that a user has
reported or introduces a new feature that Fedora users have previously
requested. Even still, for more complex packages it might make sense to
backport the specific patch needed.

The risk of serious regressions always exists and should be considered.
Rawhide is the development branch, so package maintainers may choose to
push an update to rawhide for a period before pushing to a release
branch. This gives rawhide testers the opportunity to catch any issues
before <code>updates-testing</code> or <code>updates</code> users can be
affected.

== Update Descriptions ==

Fedora users who do not update automatically may review the descriptions
attached to updates before choosing whether they should apply them.

Package maintainers should bear this in mind when preparing the update
description and try to help their users make as informed decisions as
possible.

Some suggestions for what a description might include:

# For security issues, links to the appropriate CVEs 
# For bug fixes, links to any relevant bugzillas
# For new upstream releases, a summary of the important changes and/or
  a link to the upstream changelog
# Any other information that might be important to users

Good judgement is required, though. Overly verbose descriptions can be
almost as useless as overly terse descriptions.

== Rate of Updates ==

Package maintainers should bear in mind that not all Fedora users have
good Internet bandwidth available.

Where a package is likely to require many small updates in a short
period of time, a maintainer may decide to combine those into a single
update. This is especially important in the case of large packages.

[[Category:Package Maintainers]]