QUIP 5 - Choosing a Branch

Change-Id: I168e77576d40551094acef0e1618d0d89a2b113b
Reviewed-by: Robert Loehning <robert.loehning@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

1 files changed, 193 insertions, 0 deletions

diff --git a/quip-0005.txt b/quip-0005.txt
new file mode 100644
index 0000000..78770e8
--- /dev/null
+++ b/quip-0005.txt
@@ -0,0 +1,193 @@
+QUIP: 5
+Title: Choosing a Branch
+Author: Jędrzej Nowacki, Friedemann Kleint
+Status: Draft
+Type: Process
+Created: 2016-12-05
+Post-History: http://lists.qt-project.org/pipermail/development/2017-January/028248.html
+
+========================================
+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 <http://wiki.qt.io/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 subsequent stable branch is created (for the
+    5.6 LTS, this would have been 5.7). 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        |
++----------------------------+-----+--------+--------+-------------+---------+---------------------+
+
+Glossary
+--------
+
+RTA
+    Release testing automation
+
+References
+----------
+
+- `Branch Guidelines <http://wiki.qt.io/Branch_Guidelines>`_
+- `JIRA-Priorities <https://wiki.qt.io/JIRA-Priorities>`_