Motivation

This QUIP offers guidelines on the right branch to submit a change to. It originated from the QtCS2016 Managing Qt Branches 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 (5.X.Y)

• Preparation of the code base for a release undisturbed by activities in the stable branches

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

• Support for 3 years after its initial release, extending the stable phase
• Release roughly every 6 Months or when appropriate
• Support slower 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, like win8 => win8.1
• Add support for newer toolchains - if and only if changes are small, like adding MSVC 2015
• 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.9 LTS, the one after next is 5.11). Submitting to the LTS branch directly is then no longer possible; changes must be submitted to the stable branch and undergo some testing first before being cherry-picked into the LTS branch. 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 believe that there are no more P1 and P0 bugs.

Goal of the stable branches (5.x)

• Bug fixes
• Performance fixes
• Documentation fixes
• As a special case, pre-release stabilization immediately after branching off the dev branch

Goal of the dev branch:

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

Approach

The table below lists typical code changes, and indicates the branch the change should be pushed to. In all cases, we need to estimate the impact of the change. For example, a fix for a performance problem may end up in a different branch depending on: how many users are affected, how big is the improvement, and what is the risk of regressions. The table shows the most stable branch (i.e. right-most), for every case. If a change is risky or it has lower impact, then it should be placed in a less stable (i.e. further to the left) branch.

History

The dev / stable / release pattern originated in a discussion during initial development of Qt 5: Branching for Qt 5 repositories

Glossary

RTA

Release testing automation

References

• Branch Guidelines
• JIRA-Priorities