@@ -87,31 +87,42 @@ There is a set of tests to help identifying ABI changes:
87
87
Please, prefer updating the test files with the above command. The checker
88
88
script automatically sorts symbols. This would allow developers to avoid
89
89
large diffs and help maintainers identify the nature of ABI changes.
90
- * ` test/abi/layout* ` and ` test/abi/symbol_size_alignment.cpp ` are a group of
90
+ * ` test/abi/layout* ` and ` test/abi/symbol_size_alignment.cpp ` are a group of
91
91
tests to check the internal layout of some classes. The ` layout* ` tests check
92
- some of API classes for layout changes, while ` symbol_size_alignment ` only
92
+ some of API classes for layout changes, while ` symbol_size_alignment ` only
93
93
checks ` sizeof ` and ` alignof ` for API classes. Changing the class layout is a
94
94
breaking change.
95
95
96
96
## Changing ABI
97
97
98
- ** Note (October, 2020)** : DPC++ runtime and compiler ABI is currently in frozen
99
- state. This means that no ABI-breaking changes will be accepted by default.
100
- Project maintainers may still approve breaking changes in some cases. Please,
101
- try to avoid any breaking changes until freeze is lifted. If you need to change
102
- existing functionality, consider adding new APIs instead of replacing them.
103
- Also, please, avoid any changes, mentioned in the [ Intro] ( #intro ) section as
104
- breaking. Refer to the above guide to distinguish breaking and non-breaking
105
- changes. If not sure, do not hesitate to ask code owners for help.
98
+ Generally DPC++ runtime and compiler ABI is frozen and ABI-breaking changes are
99
+ not accepted by default since Oct 2020. Please try to avoid making any breaking
100
+ changes. If you need to change existing functionality, consider adding new APIs
101
+ instead of replacing existing APIs. Also, please, avoid any changes, mentioned in the
102
+ [ Intro] ( #intro ) section as breaking. Refer to the above guide to distinguish
103
+ between breaking and non-breaking changes. If unsure, do not hesitate to ask code
104
+ owners for help.
105
+
106
+ ** Note** : Features clearly marked as experimental are considered as an exception
107
+ to this guideline.
108
+
109
+ ### ABI breaking changes window June 15 - September 15 2022
110
+
111
+ Since the point when ABI was frozen ~ 2 years ago we have accumulated a significant
112
+ volume of changes, which require breaking ABI. We are opening a window to
113
+ implement these changes. During this period of time ABI breaking changes will be
114
+ accepted. All breaking changes will still require a good justification.
106
115
107
116
Whenever you need to change the existing ABI, please, follow these steps:
108
117
109
- 1 . Adjust you PR description to reflect (non-)breaking ABI changes. Make sure
110
- it is clear, why breaking ABI is necessary.
111
- 2 . Fix failing ABI tests in your Pull Request. Use aforementioned techniques to
118
+ 1 . Add [ ABI-break ] tag to your PR title.
119
+ 2 . Update your PR description with rationale why breaking ABI is necessary.
120
+ 3 . Fix failing ABI tests in your Pull Request. Use aforementioned techniques to
112
121
update test files.
113
- 3 . ~~ If Pull Request introduces a breaking change, update the library version~~
114
- ~~ according to the policies.~~ ** (See note above)**
122
+ 4 . Increment library engineering version together with the change ("-V" postfix
123
+ part of version, as described above)
124
+
125
+ At the end of this window we will increment major version of the DPC++ library
115
126
116
127
## BKMs on avoiding changing ABI
117
128
0 commit comments