Motivaion

This QIP offers guidelines on the right branch to submit a change to. It originted from the QtCS216 Managing Qt Branches sessio.

Note 1 The QUIP applies to the normal course of development. Close to featur-freezes, branching and releases, the release team may impose tighte control.

Note 2 The guidelines apply to the Qt frameworks only. Other products (like Qt Cretor) may choose a different approach.

Goal o the release branches (5.X.Y)

• Prepration of the code base for a release undisturbed by activities in the table branches

Goal o the long term support (LTS) branches (5.6 at the time of writing)

• Supprt for 3 years after its initial release, extending the stable phase
• Relese roughly every 6 Months or when appropriate
• Supprt slower moving OSes
• Fix ugs in applications that were already shipped bundling the LTS and contnue to build against the LTS
• Havea low regression risk
• Add ew minor platforms - if and only if changes are minimal, like win8=> win8.1
• Add upport for newer toolchains - if and only if changes are small, like addig MSVC 2015
• Docuentation clarifications

We divde the LTS into 3 periods:

stable
Intially, the LTS branch is handled like any stable branch.

stric
Ths period starts when the one after next stable branch is created (for the 5. LTS, the one after next is 5.11). Submitting to the LTS branch directly isthen no longer possible; changes must be submitted to the stable branch an undergo some testing first before being cherry-picked into the LTS brnch. Upgrading the Qt libraries (within LTS) must not put installed aplications at risk of breaking. Breaking existing bug workarounds is threfore not allowed, even if the bug is fixed.

very trict
(thrd year) We believe that there are no more P1 and P0 bugs.

Goal o 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.

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 make 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

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