Package update guidelines

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

Package Update Guidelines

This page is intended to give some guidelines relevant to package maintainers who wish to update a package on an already-released branch. It does not apply to rawhide updates or packages just being introduced newly in the repository. These are not intended to be prescriptive rules. Package maintainers are expected to 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 updates-testing or updates users can be affected.

Update Descriptions

The description field in the bodhi interface is what the users will see on the PackageKit GUI regarding the significance of the update. This is not the same thing as th RPM SPEC file changelog.

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:

1. For security issues, links to the appropriate CVEs
2. For bug fixes, links to any relevant bugzillas
3. For new upstream releases, a summary of the important changes and/or a link to the upstream changelog
4. 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.