Motivation

In order to sustain vigorous development while maintaining stable releases without subjecting users to disruptive upgrades, the Qt framework has diverse branches, on some of which only the least disruptive of changes are permitted while, on others, developers have more freedom to change APIs and behaviors. The aim of this QUIP is to make clear which changes go into which branches, what stability commitments The Qt Project makes to its users for its various types of release, and how the former ensures the latter.

It supersedes QUIP 5 with the changes discussed at the QtCS2019 Branch Policy Session.

Note 1: The QUIP applies to the normal course of development. Close to feature-freezes, branching and releases, the release team may impose tighter control.

Note 2: The guidelines apply to the Qt frameworks only. Other products (like Qt Creator) may choose a different approach.

Goal of the release branches (X.Y.Z)

• Prepare the code-base for a release, only making changes needed for that release.

Goal of the long term support (LTS) branches (5.12 at the time of writing)

• Support for 3 years after its initial release, extending the stable phase
• Two releases each year, plus extra releases for fixes to any issues deemed critical enough.
• Support slow-moving OSes
• Fix bugs in applications that were already shipped bundling the LTS and continue to build against the LTS
• Have a low regression risk
• Add new minor platforms - if and only if changes are minimal
• Add support for newer toolchains - if and only if changes are small
• Documentation clarifications

We divide the LTS into 3 periods:

stable

Initially, the LTS branch is handled like any stable branch.

strict

This period starts when the one after next stable branch is created (for the 5.12 LTS, the one after next was 5.14). Upgrading the Qt libraries (within LTS) must not put installed applications at risk of breaking. Breaking existing bug workarounds is therefore not allowed, even if the bug is fixed.

very strict

(third year) we only accept fixes to P0 and P1 bugs, which there should be very few of by this stage.

Note: From 5.15 onwards, the extension of the stable phase becomes a service for users of Qt under the commercial license. The stable phase ends when the next minor or major release is available (typically after 6 months), and strict and very strict phases affect only commercial releases.

Goal of the stable branches (5.x)

Each stable branch is initially stabilized after branching off dev, in preparation for serving as the base for successive release branches. Once stable, the branch accepts:

• bug fixes
• performance fixes
• documentation fixes

Goal of the dev branch:

• New feature development (adding new API, classes, libraries or modules)
• Refactoring
• Risky changes, requiring longer testing period
• Completely new platforms

Cherry-picking

Cherry-picking can be done semi-automatically, using the Pick-to: footer in the commit message. The Pick-to: footer specifies a space-separated list of branches into which the change should be cherry-picked once the patch has been successfully merged.

Each branch listed in the Pick-to: footer will generate a cherry-pick patch on the target branch based on the latest revision of the merged patch. The owner of the new patch will be the Qt Cherry-pick Bot, and the author of the original commit will be the author of the cherry-pick. If the cherry-pick bot does not encounter any conflicts, the commit will be automatically approved and staged.

In case of any issues during the process, the original author will be set as the assignee of the cherry-pick patch, and reviewers will be copied from the original change. Author and reviewers will be notified about the issue, and can amend the patch like any regular change review.

To cherry-pick changes manually, use the -x option, and don't change the gerrit Change-Id footer. The cherry-pick must be done from the commit once it has been integrated into the published branch, not from a branch in a local clone, whose sha1 shall be different from the published version. Even when the change is a complete rewrite, it shall reference the original commit in its commit message, using a "fake" cherry-pick footer following the pattern (adapted from commit <sha1>). Submit the patch for review like any other change.

Exceptions

Changes should only be made directly on stable branches when there is no matching change to make on dev (e.g. because the code in question has been removed). In such cases, the change should be made on the newest stable branch to which it applies and cherry-picked back to any older stable branch to which it may be relevant.

Submitting changes directly to a strict LTS branch is not possible; changes must be submitted to the stable branch and undergo some testing first before being cherry-picked into a strict LTS branch.

Changes made as part of the release process (such as adding change files) should normally be kept to a minimum. Such changes should be propagated to their stable branch, any more recent stable branches, and dev.

Glossary

RTA

Release testing automation

References

• Branch Guidelines
• JIRA-Priorities