QUIP: 5 Title: Choosing a Branch Author: Jędrzej Nowacki, Friedemann Kleint Status: Superseded Type: Process Created: 2016-12-05 Post-History: https://lists.qt-project.org/pipermail/development/2017-January/028248.html Superseded-By: QUIP 16 ======================================== Choosing a Branch ======================================== 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. +----------------------------+-----+--------+----------------------+---------+---------------------+ | | | | LTS | | | | Reason for Change | Dev | Stable +--------+-------------+ 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 | | | | x | | | | (reduce flakiness) | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Adapt to minor OS/ | | | | x | | | | Compiler updates | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Memory leak | | | x | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Fix to feature added | | | x | | | | | in LTS | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Undefined behavior | | | x | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Something that makes | | | x | | | | | existing apps unstable | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Performance: significant | | | x | | | | | fix improving O() | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Performance: Issue | | x | | | | | | detected by profiling | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Performance: Issue related | x | | | | | | | to best practices (like | | | | | | | | usage of reserve()) | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Fix compiler warnings | | | x | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Suppression of false | | x | | | | e.g. static code | | positives raised by tools | | | | | | analysers | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Documentation: small fixes | | | | x | | | | (links, typos, warnings) | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Documentation: refactoring | | x | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Bugs: Easily triggered | | | | x | | | | crash | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Bugs: Hard to reproduce | | | x | | | | | crash | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Bugs: Regression | | | x | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Bugs: Hard-to-reproduce | | x | | | | | | regression noticed some | | | | | | | | time after release | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | 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 | x | | | | | | | features | | | | | | | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ | Using new C++ | x | | | | | This includes | | features | | | | | | mass updates | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ 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 `_