QUIP 6 | Acceptable Source-Incompatible Changes

QUIP:6
Title:Acceptable Source-Incompatible Changes
Version:ab240ac39d6e41f975eefd1128967ae6fdc6e31a
Last-Modified:2021-07-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

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 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
Adding an overload of a function X  
  Exception: when causing ambiguities   X
Adding Q_OBJECT to a QObject subclass that lacks it. X  
Deprecating a function/class/typedef (even though it breaks
-Werror=deprecated builds)
 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
 
Exception: when preventing API misuses at compile-time,
e.g. when constraining templates (further).
 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.