[llvm] [libsycl] SYCL Extension naming policy. (PR #226967)

[Kseniya Tikhomirova via llvm-commits]

https://github.com/KseniyaTikhomirova created https://github.com/llvm/llvm-project/pull/226967

Assisted-by: Claude Code

>From 4fcd287026e32aeaaed46a3d2fef9e876a0896e3 Mon Sep 17 00:00:00 2001
From: "Tikhomirova, Kseniya" <kseniya.tikhomirova at intel.com>
Date: Mon, 28 Sep 2026 04:44:58 -0700
Subject: [PATCH] [libsycl] SYCL Extension naming policy.

Signed-off-by: Tikhomirova, Kseniya <kseniya.tikhomirova at intel.com>
---
 libsycl/docs/CodingGuidelines.md | 87 ++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/libsycl/docs/CodingGuidelines.md b/libsycl/docs/CodingGuidelines.md
index 0709c556d78fa..d231fecdca1d2 100644
--- a/libsycl/docs/CodingGuidelines.md
+++ b/libsycl/docs/CodingGuidelines.md
@@ -31,3 +31,90 @@ Coding Standards.
   files in directories `cmake/modules` and `docs` should be named in camel
   case.
 
+### Extension Naming Policy
+
+The SYCL 2020 specification gives every vendor extension a vendor string. The
+extension's APIs are declared in the `sycl::ext::<vendor>` namespace, its
+feature-test macro is `SYCL_EXT_<VENDOR>_<NAME>`, and any enumerators or members
+it adds to core SYCL classes (for example aspects) are prefixed with
+`ext_<vendor>_`.
+
+The vendor string tells users who defines the behavior of the feature. libsycl
+picks it by that rule, not by who wrote the implementation.
+
+| Origin of the extension                                       | Vendor string                                  |
+| ------------------------------------------------------------- | ---------------------------------------------- |
+| Not defined by any vendor: designed in the LLVM community     | `llvm`                                         |
+| Defined by another vendor and implemented as specified        | The original one (e.g. `oneapi`, `intel`)      |
+| Defined by another vendor, but libsycl intentionally deviates | `llvm`, only after the deviation is justified  |
+| Ratified by Khronos                                           | `khr`                                          |
+
+#### Community Extensions
+
+An extension that the LLVM community designs itself uses the `llvm` vendor
+string, for example `sycl::ext::llvm::<name>` with the feature-test macro
+`SYCL_EXT_LLVM_<NAME>`. The community determines what such a feature is, so its
+specification must be reviewed and committed together with the implementation.
+
+#### Extensions Adopted From Another Vendor
+
+When libsycl implements an extension defined by another vendor with the intent
+to match it, the extension keeps its original name. For example, the
+`sycl_ext_oneapi_<name>` extension from intel/llvm is implemented as
+`sycl::ext::oneapi::<name>` with the feature-test macro
+`SYCL_EXT_ONEAPI_<NAME>`. The original vendor's specification defines the
+feature:
+
+- Any behavioral difference from that specification is a libsycl bug.
+- The implementation refers to the specification and to the revision of it that
+  is implemented.
+- The feature-test macro is defined, with the value of the implemented revision,
+  only once that revision is fully implemented. Until then, the missing parts
+  are listed in `libsycl/docs/index.md`.
+- Differences that the specification does not make observable, such as
+  implementation details, unspecified behavior, or diagnostic wording, are not
+  deviations.
+- If the specification appears to be wrong, the problem is raised with the
+  vendor that owns it rather than fixed only in libsycl.
+- New revisions of the specification are followed. An incompatible revision is
+  implemented by updating to it and to its feature-test macro value.
+
+Both `oneapi` and `intel` extensions are defined by Intel in intel/llvm and
+follow this rule. `oneapi` extensions are designed to be device-agnostic, while
+`intel` extensions expose features of Intel hardware or backends. The vendor
+string of an `intel` extension stays `intel` even when libsycl implements it on
+other devices, because it names the owner of the definition, not the hardware.
+
+#### Deviating From Another Vendor's Extension
+
+A deviation is any intentional change to the specified behavior: a different API
+shape, different semantics, or a reduced or extended scope. Before deviating,
+question why and whether it is a good idea. Two features with nearly the same
+name but different behavior confuse users and force them to write more `#if`
+blocks to use the feature portably. Proposing the change to the owning vendor is
+preferred.
+
+If the deviation is still justified, the extension is spelled with the `llvm`
+vendor string, e.g. `sycl::ext::llvm::<name>`, to signal that it is not
+`sycl::ext::oneapi::<name>`. It is then a community extension with its own
+specification. The original vendor's spelling must not be used for the deviating
+extension, including as an alias.
+
+#### Khronos Extensions
+
+Extensions ratified by Khronos use the `khr` vendor string and are implemented
+as specified, following the same rules as extensions adopted from another
+vendor. When a vendor extension that libsycl implements is promoted to a `khr`
+extension, libsycl implements the `khr` extension, and the vendor version is
+deprecated.
+
+#### Rationale
+
+C++ attributes follow the same model. When GCC defines an attribute and Clang
+implements it with the same behavior, Clang accepts the `gnu` spelling, as in
+`struct [[gnu::packed]] S`, because GCC defines what the attribute means.
+Adding it only as `[[clang::packed]]` would leave users unsure how
+`gnu::packed` and `clang::packed` differ and would make portable code need
+more `#if` blocks. Clang uses its own `clang` namespace for attributes it
+defines itself.
+