Kokkos version major/version minor (Feature request)

[jjwilke]

Related to #1031.

Kokkos should define a major and minor version in the CMake. This would at least allow us to do cmake compatibility checks if someone is using the "preferred" method of CMake packages - since they could request a particular major version.

I'm not sure if there is a versioning model for Kokkos? I would recommend all minor versions be required be API-preserving. Major versions not required to be API conforming.

In reference to #1031 - CMake package magic would ensure headers and libraries are the same version and the version you requested in your CMake.

[ndellingwood]

@jjwilke git tag -l provides the version for kokkos. The major version has corresponded to copyright asserts; the minor version has corresponded to substantial changes, and the sub-minor version (not sure what to call it) corresponds to when a promotion occurs tracking the number of weeks since the previous minor update.
These are also tracked in the master_history.txt file, here's a bit of a description in the kokkos-promotion document, hopefully it's helpful.

[crtrott]

API breakage is mainly limited to major versions. Thats what delayed the 3.0 release, because we didn't finish deprecated everything we want to deprecate until the last version.

[jjwilke]

Added versions matching the git tag -l output. I set CMake compatibility to SAME_MAJOR_VERSION - which assumes that any two kokkos major versions are API-compatible. The other common option is ANY_GREATER_VERSION, but it sounds like this would be incorrect.

[crtrott]

Minor versions are backward compatible but not forward. And only from the user perspective. We do not guarantee ABI compatibility in any way shape or form at this point.

[jjwilke]

Okay. That is exactly the behavior of cmake SAME_MAJOR_VERSION. Minor versions are assumed to be backwards but not forward compatible.

[mhoemmen]

The main value of the minor version number is for apps that don't update their Kokkos continuously and may need to support multiple versions in order to get integrations right. For example, the change from dimension to extent was still within the same major release.

[jjwilke]

Was that done in a non-backward compatible way? My understanding of "best practice" would be to avoid breaking backwards compatibility on minor version numbers (which is potentially why Cmake makes this the easiest versioning model to support).

This would only be relevant going forward as the new CMake is in a feature branch at this point. Probably worth discussing whether we want to follow this model in the future.

[ndellingwood]

@jjwilke dimension_* is usable and still exists when KOKKOS_ENABLE_DEPRECATED_CODE=ON for backward compatibility, which is the current default. The macro will be turned OFF during the next update, in which case use of the dimension_* methods will result in a compiler error (unless users explicitly set KOKKOS_ENABLE_DEPRECATED_CODE=ON).

@crtrott just to confirm, the next release when we flip the switch to OFF with deprecated code is to be considered a minor release, with the next major release to coincide with the copyright update?

[jjwilke]

I believe I can put in logic to activate KOKKOS_ENABLE_DEPRECATED_CODE when an older minor version is requested, which should then be enough to guarantee minor version backwards compatibility?

[ndellingwood]

@jjwilke I think that would work, thanks!

[jjwilke]

Basic logic is implemented here

As needed, we should be able to modify for changing backwards compatibility conditions

[dalg24]

@jjwilke Did you work on this?

[jjwilke]

We export version numbers that allow people to request specific versions. There was some discussion of deprecated code previously. I would say let's just declare major version compatibility only. We don't really have backwards compatibility. You'd have to set the deprecated code option when installing Kokkos.

We can revisit this for 4.0. In a manner of speaking, 3.0 is "1.0" for the build system. If we decide that someone requesting 3.1 should be able to use 4.0, I can change SAME_MAJOR_VERSION logic without issue.

TL;DR Yes, this is done.