Skip to content

Commit

Permalink
[SYCL][Doc] Announce ABI-breaking window (intel#6274)
Browse files Browse the repository at this point in the history
Preparation for the next major library version release

Co-authored-by: Steffen Larsen <steffen.larsen@intel.com>
  • Loading branch information
Pavel Chupin and steffenlarsen authored Jun 10, 2022
1 parent 3ed96a4 commit 6db064a
Showing 1 changed file with 26 additions and 15 deletions.
41 changes: 26 additions & 15 deletions sycl/doc/developer/ABIPolicyGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 6db064a

Please sign in to comment.