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
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
QUIP: 16
Title: Branch policy
Author: Volker Hilsheimer
Status: Active
Type: Process
Created: 2020-04-29
Post-History: https://lists.qt-project.org/pipermail/development/2019-November/037927.html
Replaces: QUIP 5
========================================
Branch policy
========================================
Motivation
----------
In order to sustain vigorous development while maintaining stable releases without subjecting
users to disruptive upgrades, the Qt framework has diverse branches, on some of which only the
least disruptive of changes are permitted while, on others, developers have more freedom to
change APIs and behaviors. The aim of this QUIP is to make clear which changes go into
which branches, what stability commitments The Qt Project makes to its users for its various
types of release, and how the former ensures the latter.
It supersedes QUIP 5 with the changes discussed at the
`QtCS2019 Branch Policy 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.
.. _`QtCS2019 Branch Policy Session`: https://wiki.qt.io/Qt_Contributors_Summit_2019_-_Branch_Policy
==================
Types of Branches
==================
Goal of the release branches (X.Y.Z)
------------------------------------
- Prepare the code-base for a release, only making changes needed for that release.
Goal of the long term support (LTS) branches (5.12 at the time of writing)
--------------------------------------------------------------------------
- Support for 3 years after its initial release, extending the stable phase
- Two releases each year, plus extra releases for fixes to any issues deemed
critical enough.
- Support slow-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
- Add support for newer toolchains - if and only if changes are small
- 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.12 LTS, the one after next was 5.14). 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 only accept fixes to P0 and P1 bugs, which there should be very
few of by this stage.
*Note*: From 5.15 onwards, the extension of the stable phase becomes a service for
users of Qt under the commercial license. The stable phase ends when the next minor
or major release is available (typically after 6 months), and *strict* and
*very strict* phases affect only commercial releases.
Goal of the stable branches (5.x)
---------------------------------
Each stable branch is initially stabilized after branching off dev,
in preparation for serving as the base for successive release branches.
Once stable, the branch accepts:
- bug fixes
- performance fixes
- documentation fixes
Goal of the dev branch:
-----------------------
- New feature development (adding new API, classes, libraries or modules)
- Refactoring
- Risky changes, requiring longer testing period
- Completely new platforms
========
Workflow
========
Changes are generally developed and submitted against the dev branch. Changes
that qualify for a stable, strict, or release branch may be cherry-picked into
those branches once the merge into dev is completed. This might require some
backporting and adjustments, or even a complete rewrite of the change. All
cherry-pick changes need to reference the original commit.
Cherry-picking
--------------
Cherry-picking can be done semi-automatically, using the `Pick-to:` footer in
the commit message. The `Pick-to:` footer specifies a space-separated list of
branches into which the change should be cherry-picked once the patch has been
successfully merged.
Each branch listed in the `Pick-to:` footer will generate a cherry-pick patch on
the target branch based on the latest revision of the merged patch. The owner of
the new patch will be the `Qt Cherry-pick Bot`, and the author of the original
commit will be the author of the cherry-pick. If the cherry-pick bot does not
encounter any conflicts, the commit will be automatically approved and staged.
In case of any issues during the process, the original author will be set as the
assignee of the cherry-pick patch, and reviewers will be copied from the original
change. Author and reviewers will be notified about the issue, and can amend the
patch like any regular change review.
To cherry-pick changes manually, use the `-x` option, and don't change the
gerrit `Change-Id` footer. The cherry-pick must be done from the commit once
it has been integrated into the published branch, not from a branch in a local
clone, whose sha1 shall be different from the published version. Even when the
change is a complete rewrite, it shall reference the original commit in its
commit message, using a "fake" cherry-pick footer following the pattern
`(adapted from commit <sha1>)`. Submit the patch for review like any other change.
Exceptions
----------
Changes should only be made directly on stable branches when there is no
matching change to make on dev (e.g. because the code in question has been removed).
In such cases, the change should be made on the newest stable branch to which it
applies and cherry-picked back to any older stable branch to which it may be relevant.
Submitting changes directly to a strict LTS branch is not possible; changes
must be submitted to the stable branch and undergo some testing first before
being cherry-picked into a strict LTS branch.
Changes made as part of the release process (such as adding change files) should
normally be kept to a minimum. Such changes should be propagated to their stable
branch, any more recent stable branches, and dev.
===============================
Types of changes to cherry-pick
===============================
The table below lists typical code changes, and indicates the branch the
change may be cherry-picked to. 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 only be cherry-picked to a less stable (i.e. further to the left)
branch.
Types of changes not listed here are in general only relevant for the dev branch,
and do not get cherry-picked. In particular, any feature addition, refactoring,
or adoption of new C++ language features does not get cherry-picked.
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.
+----------------------------+--------+----------------------+---------+---------------------+
| | | LTS | | |
| Reason for Change | Stable +--------+-------------+ Release | Notes |
| | | Strict | Very Strict | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Binary compatibility | | | | x | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Source compatibility | | | | x | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| API review finding | | | | x | Initial release |
| | | | | | only |
+----------------------------+--------+--------+-------------+---------+---------------------+
| RTA/package test finding | | | | x | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Security issue | | | | x | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| 3rd party update | | | x | | Very Strict only |
| | | | | | security/critical |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Adapt to minor OS/ | | | x | | |
| Compiler updates | | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Memory leak | | x | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Feature added in this | | x | | | |
| minor version | | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Undefined behavior | | x | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Something that makes | | x | | | |
| existing apps unstable | | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Performance: significant | | x | | | |
| fix improving O() | | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Performance: Issue | x | | | | |
| detected by profiling | | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Compiler warnings | | x | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| False positives | x | | | | e.g. static code |
| raised by tools | | | | | analysers |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Documentation: small fixes | | | x | | |
| (links, typos, warnings) | | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Documentation: refactoring | x | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Tests: flakiness | | | x | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
| Tests: 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 | | | | |
+----------------------------+--------+--------+-------------+---------+---------------------+
Glossary
--------
RTA
Release testing automation
References
----------
- `Branch Guidelines <http://wiki.qt.io/Branch_Guidelines>`_
- `JIRA-Priorities <https://wiki.qt.io/JIRA-Priorities>`_
|
