[RFC|oneMKL]Enable programmatic versioning

[vmalia]

Motivation

• Customers of oneMKL have requested a way to query the spec-compliance version of the implementation.
• The specification defines versioning but not in a programmatic way.
• Addresses Incomplete documentation about spec versioning #551

Inspiration

• SYCL versioning does not add the revision number:

---

• OpenMP specification itself keeps only MAJOR.MINOR version, with ongoing progress marked as Technical Report <number>. The _OPENMP macro provides a release date which maps onto a specification version, like this:

#define _OPENMP 202111    //202111: OpenMP 5.2

Proposal

• <MAJOR><MINOR><REVISION> such that MINOR and REVISION have two digits.
• Propose a macro for oneAPI and suggest a naming scheme for component macro names.

[rscohn2]

@uxlfoundation/oneapi-spec-maintainers: Please review this versioning proposal

[andrewtbarker]

I do not understand what is being proposed here.

Is the idea that each implementation of the spec gets to decide how to provide a version to the user (whether by a version string, a #define, an int getSpecVersion() function)? Then this change to the spec only specifies that the end of this string/macro/int has a certain representation?

[vmalia]

Is the idea that each implementation of the spec gets to decide how to provide a version to the user (whether by a version string, a #define, an int getSpecVersion() function)? Then this change to the spec only specifies that the end of this string/macro/int has a certain representation?

Yes. The goal of this RFC is to ensure that every implementation of the spec provides a numerically comparable value for its compliance with the spec version, through the proposed macros.

The implementation can additionally provide more ways to query that information, like APIs, but we do not mandate that in this proposal.

[vmalia]

@akukanov @mkrainiuk @rscohn2 @spencerpatty if everything looks okay, then please provide your approval. Thank you!

[spencerpatty]

Acceptable from my perspective. Approved

[vmalia]

@aelizaro @paveldyakov @lhuot @zettai-reido @sknepper can you please provide your reviews? Thank you!

[spencerpatty]

If/When we switch to oneMATH name for the Specification and Interfaces project, will we also switch the macro names ? maybe we want to delay this merge until those are made to not have to deprecate/switch ... ?

[vmalia]

@spencerpatty The changes you mentioned are from oneapi-src/oneMKL#564 which is an RFC in one of the implementations of this spec. The implementation can choose to take any direction, whether or not it is in compliance with the specification.

@Rbiessy you approved this PR earlier so there are 2 questions -

1. Does your RFC([RFC] oneMKL Interface renaming oneapi-src/oneMKL#564) block this RFC?
2. Does your RFC aim to make changes to the oneAPI specification eventually? If yes, can you please create a placeholder Issue/PR in this project and mention it here? If not, please note that your oneMKL Interfaces RFC breaks compliance with the oneAPI specification as of the current status of your RFC.

Note point number 5 in https://github.com/mkrainiuk/oneMKL/blob/rfcs/README.md#rfc-ratification-process

[vmalia]

I had an offline discussion with the team and we came to an agreement that the oneMATH proposal has a lot of work ahead of it, and that name change will have to be made in not just oneMKL Interfaces, but also in multiple places across oneAPI spec and other documents. Since this change will have a wider impact than just this specific part of document where this PR targets, it is better to make that change at that time. It will not affect the core version schema or approach proposed here.
This PR and RFC is NOT blocked by @Rbiessy 's RFC in oneMKL Interfaces.

[Rbiessy]

It does not matter to me which RFC is implemented first. The RFC for renaming is planning to rename the occurrences of all the macros using ONEMKL.
The RFC describes how it impacts the specification. I read the ratification process, it does not say that an issue needs to be created. @mkrainiuk could this be clarified in the RFC process? I created #580 but I have some concerns the discussions will be split in 2 different places now.

[mkrainiuk]

Hi @Rbiessy, good point, we need to clarify it in the ratification process, and I think any changes related to API should be discussed in Spec only, since opensource is just an implementation of the Spec, I believe it should just follow what was decided for Spec. In this particular case I guess the problem is that we have opensource project migration (which is not related to the Spec) combined with renaming (which is Spec related and should be started in the Spec).

[vmalia]

Thank you for clarifying, @mkrainiuk . @spencerpatty @Rbiessy Let's proceed with this RFC with the oneMKL naming. When the oneMATH proposal is made to the oneAPI spec, it can address these macros and other changes across the oneAPI spec simultaneously.

[akukanov]

For your information, below is what I propose for defining a spec version macro for oneDPL. Use as you like; in case of feedback please comment in the PR #591.

A oneDPL implementation must define a preprocessor macro representing the version
of the oneDPL specification that the implementation is compliant with.

.. code:: cpp
  // Defined in <oneapi/dpl/version>
  #define ONEDPL_SPEC_VERSION /*implementation-defined*/

The ``ONEDPL_SPEC_VERSION`` macro must be defined to the decimal literal which value equals to
*major-spec-version* * 100 + *minor-spec-version*, where *major-spec-version* and *minor-spec-version*
are the major and the minor versions of the latest fully supported specification.
[*Example*: ``#define ONEDPL_SPEC_VERSION 104`` for the oneDPL specification 1.4.  -- *end example*]