blob: 3561ff016c7ff3c5459f04f3cd894bc219d6fc77 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
|
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/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.
|
