QUIP: 6
Title: Acceptable Source-Incompatible Changes
Author: Marc Mutz
Status: Active
Type: Implementation
Post-History: http://lists.qt-project.org/pipermail/development/2016-July/026527.html
              http://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
<http://lists.qt-project.org/pipermail/development/2016-July/026543.html>`_
in the `Source break policy for function overloads
<http://lists.qt-project.org/pipermail/development/2016-July/026527.html>`_
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 <http://en.cppreference.com/w/cpp/language/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.

+-------------------------------------------------------------+-------+--------+
|                                                             | Classification |
| Source-incompatible Change                                  +-------+--------+
|                                                             | 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 |   X   |        |
|     -Werror=deprecated builds)                              |       |        |
+-------------------------------------------------------------+-------+--------+
| 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,   |   X   |        |
| |            e.g. when constraining templates (further).    |       |        |
+-+-----------------------------------------------------------+-------+--------+

¹ 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++
  <https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B>`_

- `SFINAE <http://en.cppreference.com/w/cpp/language/sfinae>`_

- `Source break policy for function overloads
  <http://lists.qt-project.org/pipermail/development/2016-July/026527.html>`_
  mailing-list thread.