Motivation

Qt strives to keep source compatibility as much as possible within a major Qt release, i.e. between minor releases.

We acknowledge that there can be exceptional situations where adding new functionality or fixing issues requires changes that might break existing code.

This QUIP offers guidelines on which types of source-incompatible changes may be acceptable between minor releases.

It originated from the author’s post in the Source break policy for function overloads mailing-list thread.

Classification of Source-Incompatible Changes

We classify source-incompatible changes (SiCs) into two categories: A and B.

Category A SiCs break existing code, but can be worked around in user code without introducing Qt version checks.

Category B SiCs break existing code, and need to be worked around in user code using Qt version checks, or similar techniques, such as SFINAE.

Category A SiCs are acceptable, while Category B SiCs are not.

Category B SiCs can be made acceptable when hidden behind an opt-in macro. Deprecations and QT_NO_x macros are the primary examples of such opt-in mechanisms.

User Notification

Accepted SiCs need be communicated to users by way of changelog entries at the library level, using the tag [Potentially Source-Incompatible Changes], see QUIP 17 for details.

Examples

This list is not exhaustive. Issues not listed here should be discussed on the mailing-list and then added here.

#	Source-incompatible Change	Classification
		Cat A	Cat B
A.1	Adding an overload of a function	X
B.1	Exception: when causing ambiguities		X
A.2	Adding Q_OBJECT to a QObject subclass that lacks it.	X
A.3	Deprecating a function/class/typedef (even though it breaks -Werror=deprecated builds)	X
A.4	Removing an include from a public header file	X
A.5	Removing top-level const from return types (see1)	X
B.6	Removing/restricting public API (even if binary-compatible)		X
A.6	Exception: when preventing API misuses at compile-time, e.g. when constraining templates (further).	X
B.7	Moving declarations between headers that don't include each other (see2).		X
A.7	Exception: when moving classes (we promise SC only for use of <QStyleHeaders>, not the qstyleheaders.h)	X

---

1. 1: On compilers, such as MSVC, that mangle the return type, this is a BiC change if the function is exported. In this case, the const needs to be kept for these compilers until the next BC break, usually the next major Qt release.↩︎

2. 2: This is technically SiC A, if the target header exists in the X.Y.0 release of Qt in which the definition was introduced, but the project decided that we do not want these, because it would mean unnecessary churn for Qt users.↩︎

References

• Binary Compatibility Issues With C++
• SFINAE
• Source break policy for function overloads mailing-list thread.