[RFC] oneMKL Interface renaming

rfcs/20240903-onemkl-interface-rename/README.md

@@ -0,0 +1,205 @@
+# OneMKL Interface renaming
+
+### Revision
+
+
+|Date       |Revision | Comments                                                                 |
+|-----------|---------|--------------------------------------------------------------------------|
+|  20240903 |  1.0    | Initial version                                                          |
+|  20240916 |  1.1    | Rename occurrences of "mkl" and add an open question                     |
+
+## Motivation
+
+As oneMKL interface is moving to the UXL foundation we should make sure that the
+name does not collide with the existing [Intel oneMKL
+product](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html).
+
+We have been discussing 2 solutions to avoid this issue:
+1. Renaming the [oneMKL](https://github.com/oneapi-src/oneMKL) GitHub project to
+   a new name to be discussed and replacing or clarifying the occurrences of
+   "oneMKL" in that repository.
+2. Using this opportunity to also split this GitHub project per domain. In this
+   case the names that are advertised would be based on each domain of oneMKL
+   like `one<Domain>`.
+
+We think that the first solution should be enough to answer the main concern. It
+is not clear whether the second solution could better answer the need of users
+so we are not planning to split oneMKL per domain unless there is clear and
+strong feedback from users.
+
+**We aim to agree on a solution by October 4, 2024 and have the proposal
+implemented by the end of January 2025.**
+
+There has been a number issues of where we have had to clarify the differences
+between oneMKL Interface and the Intel oneMKL product
+[#501](https://github.com/oneapi-src/oneMKL/issues/501#issuecomment-2134681621);
+[#377](https://github.com/oneapi-src/oneMKL/issues/377);
+[#253](https://github.com/oneapi-src/oneMKL/issues/253);
+[#222](https://github.com/oneapi-src/oneMKL/issues/222);
+[#211](https://github.com/oneapi-src/oneMKL/issues/211);
+[#207](https://github.com/oneapi-src/oneMKL/issues/207);
+[#206](https://github.com/oneapi-src/oneMKL/issues/206). Many of these issues
+are from 2022. I believe this is still an issue today since this has been an
+issue on multiple occasion internally when Codeplay started to contribute to
+oneMKL Interface. The oneMKL Interface
+[README](https://github.com/oneapi-src/oneMKL?tab=readme-ov-file#onemkl) already
+explains the differences between oneMKL Interface and Intel oneMKL product but
+this is not enough for people who are not working directly on the projects.
+
+## Outline
+
+1. [Introduction](#introduction)
+2. [Proposal](#proposal)
+3. [User impact](#user-impact)
+4. [Open questions](#open-questions)
+
+## Introduction
+
+oneMKL Interface has historically been implemented and supported by Intel. As
+the project is moving to the UXL foundation we want to avoid using the name of
+an Intel product. This RFC describes the solution of renaming oneMKL Interface
+to a new name.
+
+## Proposal
+
+The main purpose of this RFC is to agree on a new name for the oneMKL specification and oneMKL Interface.
+Some of the suggested names for the implementations are:
+* **oneMath**
+  * The specification would be renamed oneMath Specification
+  * The C++ namespace would be `oneapi::math`
+  * The CMake namespace would be `ONEMATH`
+* **oneSLA** (SYCL Linear Algebra)
+  * The specification would be renamed oneSLA Specification
+  * New namespace would be `oneapi::sla`
+  * The CMake namespace would be `ONESLA`
+
+Other suggestions are welcomed. The name **oneMath** will be chosen if there are
+no objections by October 4, 2024.
+
+The suggested solution is to proceed in the following steps:
+1. The UXL foundation agrees on the new name.
+2. Codeplay submits a oneAPI-spec PR to rename the occurrences of "oneMKL" and
+   "mkl" to the new name.
+3. Codeplay submits a oneMKL Interface PR to:
+  * Update the root README to use the new name, with a mention that the project
+    was formerly called oneMKL Interface.
+  * Update the references to "oneMKL" and `onemkl_` in the documentation as
+    seen in the first few lines of
+    [docs/onemkl-datatypes.rst](https://github.com/oneapi-src/oneMKL/blob/develop/docs/onemkl-datatypes.rst?plain=1#L1)
+    for instance.
+  * Update occurrences of "onemkl" in internal functions such as
+    [onemkl_cublas_host_task](https://github.com/oneapi-src/oneMKL/blob/1ce98a699f93bd3a78350269b2e34d822fe43b91/src/blas/backends/cublas/cublas_task.hpp#L77).
+  * Update macros such as include guards and other internal macros like
+    `ONEMKL_EXPORT` to use the new name.
+  * Rename CMake targets `onemkl` and `onemkl_<domain>_<backend>` to use the
+    new name. The existing targets name can be added with a deprecation
+    messages for anyone using them. See the section on [CMake target
+    deprecation](#cmake-deprecated-target) for more details. The namespace of
+    the exported and installed targets are changed to use the new name.
+  * The namespace `oneapi::mkl` is deprecated and aliased to the new namespace
+     name.
+  * The main header and domain headers are deprecated and include the new headers as shown below:
+    * `include/oneapi/`
+      * `mkl.hpp` -> `onemath.hpp`
+      * `mkl/` -> `onemath/`
+        * `blas.hpp`
+        * `dft.hpp`
+        * `lapack.hpp`
+        * `rng.hpp`
+        * `sparse_blas.hpp`
+4. Once the PRs are approved, Codeplay transfers the
+   [oneMKL](https://github.com/oneapi-src/oneMKL) GitHub project to the
+   [uxlfoundation](https://github.com/uxlfoundation) organization under the new
+   name. We use the
+   [transferring](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository)
+   feature from GitHub so the links from the previous repository are redirected
+   to the new one.
+5. The PRs from the step 2 and 3 are merged.
+
+We suggest to keep the deprecated features for 1 year before removing them.
+
+### CMake target deprecation
+
+CMake allows to set a
+[`DEPRECATION`](https://cmake.org/cmake/help/latest/prop_tgt/DEPRECATION.html)
+property on a target which will print a custom message whenever the target is
+used. The property cannot be set on an [alias
+target](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#alias-targets)
+as they are read-only. The property can be set on an imported target instead
+like the example below:
+
+```cmake
+add_library(onemath lib.cpp) # New main target, for the example
+
+add_library(onemkl INTERFACE IMPORTED) # onemkl works like an alias of onemath which can have different properties
+target_link_libraries(onemkl INTERFACE onemath)
+set_target_properties(onemkl PROPERTIES DEPRECATION "onemkl target is deprecated, please use onemath instead")
+
+add_executable(main main.cpp)
+target_link_libraries(main PUBLIC onemkl) # Prints a warning at CMake configuration time
+```
+
+The same solution can be used for the `onemkl_<domain>_<backend>` targets. This does
+not add any extra targets to the generated `Makefile` or `build.ninja` files so
+the library will not be built twice.
+
+### Other Considered Approaches
+
+Another considered approach is to split the existing oneMKL Interface per domain
+like so: oneBLAS, oneLAPACK, oneDFT, oneRNG, oneSPARSE. This shifts the need of
+renaming "oneMKL Interface" as the main visible names will be based on the
+domain. It is not clear whether this better answers the users needs.
+
+With this approach the suggested solution is to have a common repository for
+common types (`transpose`, `uplo`, `diag`, `side`, `offset`, `index_base`,
+`layout`), exceptions and some CMake logic. Each domain would have its own
+repository automatically pulling the common headers. Another repository could be
+created to automatically pull multiple domains which would mimic the behavior of
+the current oneMKL Interface.
+
+We are not planning to proceed with this approach unless users express a strong
+preference.
+
+## User impact
+
+The suggested solution can break user's code in 2 ways:
+* Only the headers listed below should be included by the users. Any other
+  headers will be moved and will not have an equivalent header with a
+  deprecation warning.
+  * `include/oneapi/`
+    * `mkl.hpp`
+    * `mkl/`
+      * `blas.hpp`
+      * `dft.hpp`
+      * `lapack.hpp`
+      * `rng.hpp`
+      * `sparse_blas.hpp`
+* The CMake logic using the `MKL::` or `ONEMKL::` namespaces will need to be
+  renamed to a new namespace based on the chosen name.
+
+The following changes have no impact:
+* The repository is transferred using the [GitHub
+  transfer](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository)
+  feature so users accessing or pulling from
+  https://github.com/oneapi-src/oneMKL will be redirected to the new link.
+* The changes in oneMKL do not affect the public API. The macros renamed or the
+  header files in the `detail` folders renamed should not be used outside of the
+  oneMKL Interface project.
+* The CMake changes will still provide the same targets but will print a warning
+  message if users use targets with the `onemkl` name.
+
+## Open questions
+
+* Other suggestions for new names are welcomed.
+* Is it needed to rename the occurrences of "mkl"? 
+  * From the feedback gathered, users and maintainers are keen to rename these
+    occurrences.
+* Should the specification and the existing implementation have different names?
+  * Currently both the specification and implementation are named based on
+    "oneMKL" which suggests that the oneMKL Interface is the main or only
+    implementation of the specification. If the goal of the specification is to
+    encourage for multiple implementations to co-exist then it should be named
+    differently than the implementation.
+  * Given the nature of the project that allows for multiple backends I don't
+    see any value in encouraging multiple implementations as of today.
+  * Using multiple names may create more confusion.