QUIP 5 | Choosing a Branch

Title:Choosing a Branch
Author:Jędrzej Nowacki, Friedemann Kleint
Superseded-By:QUIP 16

Choosing a Branch


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:

Initially, the LTS branch is handled like any stable branch.
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)


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.

Reason for Change Dev Stable LTS Release Notes
Strict Very Strict
Binary compatibility break         x  
Source compatibility break         x  
API review finding         x Initial release only
RTA/package test finding         x  
Security         x  
3rd party update       x   Very Strict only security/critical
Test improvement (reduce flakiness)       x    
Adapt to minor OS/ Compiler updates       x    
Memory leak     x      
Fix to feature added in LTS     x      
Undefined behavior     x      
Something that makes existing apps unstable     x      
Performance: significant fix improving O()     x      
Performance: Issue detected by profiling   x        
Performance: Issue related to best practices (like usage of reserve()) x          
Fix compiler warnings     x      
Suppression of false positives raised by tools   x       e.g. static code analysers
Documentation: small fixes (links, typos, warnings)       x    
Documentation: refactoring   x        
Bugs: Easily triggered crash       x    
Bugs: Hard to reproduce crash     x      
Bugs: Regression     x      
Bugs: Hard-to-reproduce regression noticed some time after release   x        
Bugs: Other   x        
New modules x          
New features x          
Major build system changes x          
Refactoring: tests   x        
Refactoring: non-test code x          
Refactoring: build system x          
Enabling new compiler features x          
Using new C++ features x         This includes mass updates


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


Release testing automation