QUIP 6 | Acceptable Source-Incompatible Changes
QUIP: | 6 |
---|---|
Title: | Acceptable Source-Incompatible Changes |
Version: | 61fb930f11cabdb50559faa1ee777aaeb9800463 |
Last-Modified: | 2019-02-14 |
Author: | Marc Mutz |
Status: | Active |
Type: | Implementation |
Post-History: | https://lists.qt-project.org/pipermail/development/2016-July/026527.html https://lists.qt-project.org/pipermail/development/2017-January/028340.html |
Created: | 2017-01-13 |
Contents
Acceptable Source-Incompatible Changes
Motivation
This QUIP offers guidelines on which types of source-incompatible changes are acceptable within a major Qt release, i.e. 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.
User Notification
Accepted SiCs need be communicated to users by way of changelog entries of the form:
[ChangeLog][Potentially Source-Incompatible Changes]
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 | ||
Adding an overload of a function | X | ||
Exception: when causing ambiguities | X | ||
Adding Q_OBJECT to a QObject subclass that lacks it. | X | ||
|
X | ||
Removing an include from a public header file | X | ||
Removing top-level const from return types (see footnote 1) | X | ||
Removing/restricting public API (even if binary-compatible) | X | ||
|
X |
- ¹ 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.
References
- Binary Compatibility Issues With C++
- SFINAE
- Source break policy for function overloads mailing-list thread.