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