Skip to content

Commit bd675fe

Browse files
committed
[SYCL][DOC] Describe process of prototyping KHR extensions
1 parent 29044ff commit bd675fe

File tree

1 file changed

+46
-0
lines changed

1 file changed

+46
-0
lines changed
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Considerations for working on KHR extensions
2+
3+
SYCL specification evolves through embedding extensions developed by various
4+
vendors, including Khronos Group itself (`khr` extensions).
5+
6+
In order for a KHR extension to be accepted, there must be CTS tests for it and
7+
at least one implementation which passes them.
8+
9+
Considering that KHR extensions are being developed in public, we can start
10+
prototyping them as soon as corresponding PR for an extension is published at
11+
KhronosGroup/SYCL-Docs.
12+
13+
However, we shouldn't be exposing those extensions to end users until the
14+
extension if finalised, ratified and published by Khronos - due to risk of an
15+
extension changing during that process and lack of the officially published
16+
version of it.
17+
18+
So, we can have a PR but can't merge it. Keeping PRs opened for a long time is a
19+
bad practice, because they tend to get stale: there are merge conflicts,
20+
potential functional issues due to the codebase changes, etc.
21+
22+
In order for us to avoid stale PRs, all functionality which is a public
23+
interface of an "in-progress" KHR extension, must be hidden under
24+
`__DPCPP_ENABLE_UNFINISHED_KHR_EXTENSIONS` macro. That way we can merge a PR to
25+
avoid constantly maintaining it in a good shape, start automatically testing it
26+
but at the same time avoid exposing incomplete and/or undocumented feature to
27+
end users just yet.
28+
29+
"in-progress" KHR extension term used above is defined as:
30+
- KHR extension proposed to Khronos Group which has not been published in a
31+
released revision of the SYCL specification (of any version).
32+
33+
Note: merge of an extension proposal PR into KhronosGroup/SYCL-Docs repo is
34+
**not** considered to be a publishing event. The extension specification has
35+
to be available on the Khronos SYCL Registry website:
36+
https://registry.khronos.org/SYCL/
37+
38+
- Published KHR extension, which hasn't been fully implemented by us
39+
40+
The macro is **not** intended to be used by end users and its purpose is to
41+
simplify our development process by allowing us to merge implementation (full
42+
or partial) of the aforementioned extensions earlier to simplify maintenance and
43+
enable automated testing.
44+
45+
Due to this reason, we are not providing a separate macro for each "in-progress"
46+
KHR extension we may (partially) support, but just a single guard.

0 commit comments

Comments
 (0)