Updates policy
Fedora has differing policies for each of its branches. This document describes for maintainers what sort of updates should be created in packages for each of the various branches of existing Fedora. In the event of questions or clarifications, please file a link:https://pagure.io/fesco/new_issue[FESCo ticket] or discuss on the link:https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel list]. In general, releases should go from less conservative (Rawhide) to more so (the oldest supported stable release). This document attempts to describe when and what kinds of updates maintainers should push to Fedora users of its various branches. The link:https://fedoraproject.org/wiki/Stable_release_updates_vision#Vision_Statement[Stable release updates vision] from the Fedora Board includes more high level discussion and philosophy, while this document is more a practical guide. Refer to link:https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide[Package Update Guide] for the technical steps on pushing the updates. The link:https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle[Fedora Release Life Cycle] provides a more detailed overview of the development process.
Common updates requirements for all Fedora releases
Some critera apply to any update to any fedora branch/release:
Updating inter-dependent packages
When one updated package requires one or more other packages, the packages should be submitted together as a single update. For instance, if package A depends on packages B and C, and you want to update to a new version of package A which requires new versions of B and C, you must submit a single update containing the updated versions of all three packages. It is a bad idea to submit three separate updates, because if the update for package A is pushed stable before the updates for packages B and C, it will cause dependency problems. There is information on how to submit multi-package updates in the link:https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide/#updating_inter_dependent_packages[Package Update Guide] and information about using side-tags for multiple updates in link:https://docs.fedoraproject.org/en-US/rawhide-gating/multi-builds/[Rawhide Gating/multi-builds].
Consumable updates
link:https://bodhi.fedoraproject.org[Bodhi] updates should only be created for builds which are expected to qualify for being pushed to stable. Maintainers should not use Bodhi's testing states to test updates they never intend to push stable. This sort of testing should be done in link:https://copr.fedorainfracloud.org/[Copr] or other seperate public repositories. Consult with the QA team for further testing assistance.
link:https://fedoraproject.org/wiki/Releases/Rawhide[Rawhide] is the always-rolling development tree. Package updates built for Rawhide are composed every day and pushed out to all consumers. New builds against this tree also are added to the build root (i.e., other packages build from them). This tree is intended to meet the link:https://fedoraproject.org/wiki/Basic_Release_Criteria[Basic Release Critera] for any successfull compose so maintainers can integrate their changes with everyone else.
Repos available: link:https://fedoraproject.org/wiki/Repositories#rawhide[_rawhide_]
Since link:https://fedoraproject.org/wiki/Changes/GatingRawhidePackages[Gating Rawhide Packages] change was introduced, package updates in Fedora Rawhide need to pass verification before they land in the Rawhide repositories. This is implemented as a check for the Bodhi update, which verifies that the update satisfies the Gating policy. See link:https://docs.fedoraproject.org/en-US/rawhide-gating/single-builds/[Rawhide Gating/Single Builds] and link:https://docs.fedoraproject.org/en-US/rawhide-gating/multi-builds/[Rawhide Gating/Multi Builds] for details.
Currently the default gating policy is empty, thus a Rawhide update can pass the gate, no matter the test results. Package maintainer can opt-in for the gating of a package, by setting up individual gating policies, see link:https://docs.fedoraproject.org/en-US/rawhide-gating/optin/[How to Opt in to Gating].
As soon as a build is completed, a Bodhi update is automatically created. The update is used to gather test results. If the gating tests pass, the update is marked stable after a few minutes, pushed stable, and will be added to the next nightly compose.
For updates to Rawhide packages, maintainers MUST:
not push any known broken builds (breaks the default buildroot package set, etc.). This causes additional work for other maintainers trying to integrate their changes.
When a proposed update contains an ABI or API change: notify *a week in advance* both the link:https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel list] and maintainers directly (using the ``_packagename_-\maintainers@fedoraproject.org`` alias) whose packages depend on yours to rebuild or offer to do these rebuilds for them.
Use a side-tag when dealing with mass builds of many packages, so they can land at the same time. See link:https://docs.fedoraproject.org/en-US/rawhide-gating/multi-builds/[Rawhide Gating/Multi Builds].
Feel free to push out the newest version of packages as long as they do not cause breakage. Also keep in mind when the next Fedora release will be branched off, and be fairly confident that there will be a stable enough release in time for the next Fedora release. Otherwise you may have to back down to an older, stable version after the branching, which may involve epochs and other inconveniences.
Once a package has been added to the compose and that compose has finished and synced to the master mirrors, it will normally not be untagged. This is required to allow others to depend on the build once it has become visible. In exceptional cases, releng may untag packages.