QUIP 6: Acceptable Source-Incompatible Changes

Change-Id: Ic888eee7b3f74a910a43afaf74c60609a32ce68d
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

1 files changed, 91 insertions, 0 deletions

diff --git a/quip-0006.txt b/quip-0006.txt
new file mode 100644
index 0000000..420b051
--- /dev/null
+++ b/quip-0006.txt
@@ -0,0 +1,91 @@
+QUIP: 6
+Title: Acceptable Source-Incompatible Changes
+Author: Marc Mutz
+Status: Draft
+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][Possible 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/restricting public API (even if binary-compatible) |       |   X    |
++-+-----------------------------------------------------------+-------+--------+
+| | Exception: when preventing API misuses at compile-time,   |   X   |        |
+| |            e.g. when constraining templates (further).    |       |        |
++-+-----------------------------------------------------------+-------+--------+
+
+
+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.