Updates policy

Fedora’s "First" foundation

Fedora Linux is a fast-moving distribution by design. This is expressed in our First foundation: we provide the latest in stable and robust, useful, and powerful free software.

Our community expects Fedora to integrate new software versions from various upstreams into our repositories quickly, but with minimal disruption and in a way that fits nicely with other packages. This balance is at the heart of being a package maintainer, and this document describes our policies for working together to create the best experience for everyone.

We give individual package maintainers significant trust in how they manage and update their packages, within the Fedora Packaging Guidelines and the policies here. But, please remember that this is a collective effort. We respect, appreciate, and celebrate the work each individual maintainer puts into their packages, and we also encourage co-maintainership and collaboration to improve packaging across the entire Fedora collection.

About this 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 FESCo ticket or discuss on the 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 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 Package Update Guide for the technical steps on pushing the updates. The 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 Package Update Guide and information about using side-tags for multiple updates in Rawhide Gating/multi-builds.

Consumable updates

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 Copr or other seperate public repositories. Consult with the QA team for further testing assistance.

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 Basic Release Critera for any successful compose so maintainers can integrate their changes with everyone else.

Repos available: rawhide

Since 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 Rawhide Gating/Single Builds and 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 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 devel list and maintainers directly (using the packagename[email protected] 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 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.

  • If approved by FESCo, push pre-release versions of low level packages. FESCo approves certain packages, including (but not limited to) glibc and gcc, to provide pre-release versions here. The benefits of the early real-world testing of and upstream collaboration on these key packages far exceeds the risks that they may introduce.

Update Flow

Branched release

A Branched release exists for part of the development cycle. It starts as a fork of Rawhide and eventually becomes the next stable release. All successfull branched composes should meet the Basic Release Critera.

Branched releases use the update feedback system (Bodhi): at first just like Rawhide (updates are automatically created when a build finishes, tests run and builds are automatically pushed into the next compose), but then after Updates-testing Activation they switch to using it as stable releases do (maintainers must create updates and submit them for testing, etc).

There are several phases that a branched release goes through that affect what updates can and should be done. In general maintainers should keep in mind that this tree is being stabilized for the next release, so changes should be careful and considered and heading toward stability.

After branching, there are three freezes, Post-branch Freeze, Beta Freeze, and Final Freeze.

Post-branch Freeze

Once the new release is branched off Rawhide, the flow of updates through Bodhi is stopped until there has been a successful branched compose. This period usually lasts just a few days. Release engineering may pass some updates to stable to get the compose to complete, but otherwise all updates are paused until this initial branched compose is completed. This is to make sure we have a compose to build on and aren’t dealing with problems landing in new updates before we are ready for them.

Before Updates-testing Activation

For a short time after branching but before the Beta Freeze, the Branched release works like Rawhide: builds submitted by packagers are considered stable after passing through any gating tests via a Bodhi update, and are sent to the fedora repository directly in the next nightly compose. There are no restrictions beyond those for Rawhide at this point, but maintainers SHOULD be thinking about stabilization from this point onward, and making sure their packages will be in good condition well in advance of the stable release.

Repos available: fedora

Updates-testing Activation

At this point, the Bodhi update system is changed for the branched release to behave as it does for stable releases (see below) instead of Rawhide. From this point onward maintainers must create updates before packages become available to users and updates pass through updates-testing to allow for feedback. Updates are moved from updates-testing repository to fedora repository after appropriate karma requirements have been reached. Bodhi sets reasonable defaults for karma and enforces minimum requirements for updates. Karma requirements for updates are described below.

Repositories available: fedora, updates-testing

Maintainers SHOULD:

  • Avoid ABI/API changes where possible. If unavoidable, use a side-tag to rebuild packages.

  • Avoid any change that breaks composes of Live media, install media or testing.

  • Land any packages required for Changes planned for that release.

Beta Freeze

This freeze is scheduled to run for the three weeks leading up to the release date, but lasts until the release is signed off, even if it is delayed. During the freeze builds will not be marked stable and moved from updates-testing to fedora (and hence included in the milestone release composes) except for those approved under the Fedora QA team blocker bug process or freeze exception bug process. Once the beta release is made, the freeze is lifted. The Milestone freezes page provides more details and is the canonical reference in case of any conflict.

Once the Beta Freeze starts, we are attempting to stabilize the major versions of software that will be shipped with the final release of the OS. Major updates can be tolerated, but breaking things for early testers should be avoided if possible.

During this period:

  • All updates pulled into the release MUST fix an accepted blocker or freeze exception bug.

  • All updates still go to updates-testing.

Repositories available: fedora, updates-testing

Beta to Final Freeze

This is the time between the Beta release and the Final Freeze. The branched tree should now be stabilized and prepared for release. Major changes should be avoided during this period. Bear in mind that in most cases, the state your package has reached in the stable fedora repository at the time of the Final Freeze is the state it will be in for the final release.

Repositories available: fedora, updates-testing

Final Freeze

This freeze leads to the creation of the final release. It is similar to the Beta Freeze described above and follows the same update rules.

The updates repository is enabled at some point during this time, and packages other than freeze exception / blocker fixes are queued for so called "zero day" updates, meaning they will be available in the updates repository at the time of the release (day zero).

Repositories available: fedora, updates, updates-testing

During this period:

  • All updates pulled into the release MUST fix an accepted blocker or freeze exception bug.

  • All updates still go to updates-testing.

  • Once the updates repository is available, builds marked as stable will go there instead of to fedora.

Stable Releases

Philosophy

Releases of the Fedora distribution are like releases of the individual packages that compose it. A major version number reflects a more-or-less stable set of features and functionality. As a result, we should avoid major updates of packages within a stable release. Updates should aim to fix bugs, and not introduce features, particularly when those features would materially affect the user or developer experience. The update rate for any given release should drop off over time, approaching zero near release end-of-life; since updates are primarily bugfixes, fewer and fewer should be needed over time.

This necessarily means that stable releases will not closely track the very latest upstream code for all packages. We have Rawhide for that.

Updates should be carefully considered with respect to their dependencies. An update that required (or provided) a new Python ABI, for example, would almost certainly not be allowed. ABI changes in general are very strongly discouraged, they force larger update sets on users and they make life difficult for third-party packagers. Additionally, updates that convert resources or configuration one way (i.e., from older → newer) should be approached with extreme caution as there would be much less chance of backing out an update that did these things.

Whenever possible packagers should work with upstream to come up with stable branch releases or common patches for older releases, particularly when updating would require large dependency chain updates.

Repositories available: fedora updates updates-testing

During this period:

Exceptions

Some classes of software will not fit in these guidelines. If your package does not fit in one of the classes below, but you think it should be allowed to update more rapidly, propose a new exception class to FESCo and/or request an exception for your specific update case.

Note that you should open this dialog before you build or push updates. In the event that an issue is raised in the middle of an update already in progress, make sure you turn off autokarma pushes — this can be done while the update is pending in Bodhi.

The following things would be considered in a exception request.

Things that would make it more likely to grant a request:

  • The package is a "leaf" node. Nothing depends on it or requires it.

  • The update fixes a security issue that would affect a large number of users.

  • The update doesn’t change ABI/API and nothing needs to be rebuilt against the new version.

  • The update fixes serious bugs that many Fedora users are encountering.

Things that would make it less likely to grant a request:

  • The update converts databases or resources one way to a new format.

  • The update requires admin intervention for the service to keep working (config file format changes, etc.)

  • The update causes behavior changes (something that was denied is allowed, etc.)

  • The update changes the UI the end user sees (moves menus or buttons around, changes option names on command line)

  • The update fixes bugs that no Fedora user has reported nor would affect many Fedora users (i.e., fixes for other platforms or configurations).

Exceptions list

The following packages have been granted exceptions for the following reasons:

KDE

Refer to the KDE update policy for more details.

kernel package

  • Time and resource constraints prevent the kernel maintainers from backporting all the bug fixes, security fixes and new hardware enablement we would need to maintain older, no longer supported kernels.

  • Additionally, multiple kernels can be installed/booted, allowing users to boot older kernels in the event newer ones fail to work, and allowing time for kernel maintainers to fix any critical bugs in new kernels on older stable releases.

Rust -devel packages

This exception covers all Rust -devel packages, i.e. rpms with Rust sources. Those packages are used to build packaged Rust binaries and are not directly usable by users.

Other packages

These packages are allowed to update in stable releases:

  • the document viewer zathura and the girara library (FESCo #1255),

  • 3D printer control application prusa-slicer and the Cura stack (CuraEngine and other packages) (FESCo #2652),

  • Python code formatter python-black (FESCo #2652),

  • Python code linter ruff (FESCo #3197),

  • Python test executor python-tox (FESCo #2652),

  • command-line HTTP client httpie (FESCo #2652),

  • ownCloud Desktop Client owncloud-client (FESCo #2652).

  • KiCad EDA Software Suite kicad, kicad-packages3d, and kicad-doc (FESCo #2762).

  • HTTP parsing library llhttp (FESCo #3115).

  • Automatic Let’s Encrypt SSL tool certbot (FESCo #3124).

  • Python package and project manager uv (FESCo #3262).

Security fixes

If upstream does not provide security fixes for a particular release, and if backporting the fix would be impractical, then the package maintainer(s) MUST open a FESCo ticket for approval to rebase the package to a version that upstream supports.

Package maintainers MUST:

  • Avoid Major version updates, AI breakage, or API changes if at all possible

  • Avoid changing the user or developer experience if at all possible

FESCo will review the ticket in a timely manner and give guidance as to how the package maintainer(s) should proceed. Several common items that would make it less likely for FESCo to grant a rebase request are listed below. Please note, however, that this list is not exhaustive.

  • The update requires user or administrator intervention to keep working

  • The update requires configuration files or databases or other resources to convert to a new format

  • The update causes policy or behavior changes (such as when something that was previously denied is now allowed, etc.)

  • The update changes the way the end user interacts with the user interface (such as moving menus or buttons to a new location, changing names of command-line arguments, etc.)

  • The rebase only addresses issues that are likely to affect a subjectively small number of Fedora users

Packages with Exceptions Granted

  • kernel

Interoperability

If a package primarily serves to interoperate with hardware or network protocols, and the interface changes, then a package may be rebased if necessary. This includes network games, IM protocols, hardware music players, cell phones, etc. These packages may also be updated to add support for new devices or formats in compatible ways.

Examples of this type of package:

Database packages

Packages like virus scanners and spam filters typically have two components: a rules engine and a database. The database is expected to update frequently (sometimes not through the normal OS update mechanisms), but the rules engine is usually fairly static. However, if the maintained database changes to require a new version of the rules engine, then the package may be a candidate for rebasing.

Examples of this type of package:

Examples

  • Mozilla releases Firefox 4.0.1 with a security fix. Fedora 12 is shipping with 3.0.7, and though the bug is also present there, the fix in 4.0.1 does not apply because that part of the browser has been completely rewritten. Rebasing to 4.0.1 would be allowed since this is a security fix.

  • automake releases a new version that changes some warning conditions to errors. This would break the build process for existing packages, and would not be allowed.

  • AOL changes their instant messenger protocol in a way that requires an update to libpurple. The only upstream version of libpurple that supports the new protocol is an ABI break relative to the version in the current Fedora release. Rebasing would be allowed since this is an interoperability requirement.

  • Abiword releases a new version that adds compatibility with WordStar 4.0 documents. It also completely updates the user interface to use pie menus. This would be a feature enhancement with a major user experience change, and would not be allowed.

  • WebKit requires an update to solve a security problem. This requires updating Midori to a version with some minor menu layout changes. This would be a judgment call based on how intrusive the changes are (removing the File menu would be rude, but moving the plugin configuration menu item would be acceptable).

  • Firefox releases an update that only contains changes for other platforms. This update could be pushed to Rawhide (to keep up with the latest version), but should not be pushed to stable releases, as it does no good to our users and wastes resources to build, update, mirror, and download to our users.

  • Terminal fails to build from source when tested in a mass rebuild. An updated package should be pushed to Rawhide. Fixes for stable releases should be tested and even committed, but unless there is a problem with the previous existing build in the stable release, no update should be issued. This update would not change any user facing functions of the package.

  • KDE upstream releases a new major version, and at the same time stops supporting the older release that is in Fedora N and Fedora N-1. This release includes a large number of bugfixes, mixed with enhancements and security fixes. An exception for this type of update would need to consider: ability to backport major fixes/security issues, type and amount of bugs fixed, ability to not update other parts of Fedora for this update (i.e., avoid Qt or other base library ABI changes), amount of testing and end user visible changes. An exception like this would be on a case by case basis, based on all the above.

Karma requirements

This section describes the requirements for an update before it may be pushed from updates-testing to fedora or updates. The requirements are based on (the sum of) Bodhi karma points and the number of days the update has spent in updates-testing repository.

The push may be either by the maintainer, or automatically by Bodhi:

  • The update becomes eligible for being pushed manually after reaching the minimum "Stable by Karma" threshold for Critical path updates (yes, the same limit applies to both types of updates), OR the minimum "Stable by Time" threshold.

  • The update will be pushed automatically by Bodhi after reaching the configured "Stable by Karma" threshold, OR the configured "Stable by Time" threshold, if enabled ("Auto-request stable based on karma?" and "Auto-request stable based on time?").

  • If the update has any negative karma, the automatic push is disabled.

  • If the update reaches the "Unstable by Karma" threshold, it will be unpushed, i.e. removed from the updates-testing repository.

The maintainer is free to set the thresholds, but they cannot be lower than the minimum values described below, enforced by Bodhi. The defaults are adequate for most packages, so usually there is no need to modify the thresholds.

Security updates are subject to the same thresholds as other updates.

Non-critical path update thresholds

Critical path and EPEL update thresholds

"Critical path" updates contain at least one critical path package. Changes to this definition may only be made by FESCo or their delegate.

Problems or issues with Updates

In an effort to learn from any mistakes made, in the event of a update causing a widespread or serious problem for Fedora users, please file a FESCo ticket. FESCo will discuss and try and work to prevent the issue from happening again. A past record of such issues can be found at Updates Lessons.

OpenQA tests critpath updates in stable releases and compose artifacts for Rawhide/branched composes/release candidates.

Fedora CI runs tests on all Bodhi updates. If package maintainers have marked the tests as blocking, the Bodhi update will be blocked from going stable.

Want to help? Learn how to contribute to Fedora Docs ›