1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
QUIP: 5
Title: Choosing a Branch
Author: Jędrzej Nowacki, Friedemann Kleint
Status: Active
Type: Process
Created: 2016-12-05
Post-History: https://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 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 |
+----------------------------+-----+--------+--------+-------------+---------+---------------------+
Glossary
--------
RTA
Release testing automation
References
----------
- `Branch Guidelines <http://wiki.qt.io/Branch_Guidelines>`_
- `JIRA-Priorities <https://wiki.qt.io/JIRA-Priorities>`_
|
