Versioning Scheme about openpmd-api HOT 19 OPEN

No, I just want to deviate from it for initial pre-releases since CMake is lacking support for suffixes.

from openpmd-api.

we can publish a table on it in the docs

If we decide to go this way, it will probably be necessary.

What does -TAG stand for in your example?

Anything that semver calls pre-release identifies and build metadata (see 9 and 10). rc2 would be one such example.

from openpmd-api.

@C0nsultant as soon as we have #207 and #216 merged I would like to tag a first alpha release, e.g. 1.0.0-alpha or 1.0.0-alpha.1, so I can try to set up a conda-forge feedstock.

After that I would say we fix and finish leftovers until 1.0.0-beta.N releases and invite users to test it.

from openpmd-api.

We should be feature-ready for non-critical deployment by this point.
#70 makes us fairly light-weight with respect to dependencies, so this is indeed a suitable candidate for stepping up from dev.

When following your proposed scheme, we would tag 1.1.0-alpha. How about we start with 1.1.0-alpha.0?

from openpmd-api.

As you like, I am just trying to be compatible with semver.org and they suggest 1.0.0-alpha.1 as far as I can see.

from openpmd-api.

Hm, I usually name all our projects without the last dot. Is 1.0.0-alpha1, 1.0.0-alpha2, 1.0.0-beta1, 1.0.0-rc1, 1.0.0-rc2, 1.0.0, ... ok with you?

from openpmd-api.

Hm, CMake does not support suffixes in project(VERSION ...) and crops them in VERSION_... comparisons: https://cmake.org/pipermail/cmake-developers/2017-March/029928.html

from openpmd-api.

I will keep the alpha and beta versions with 0.1.0-... then so we can bump properly on the stable release.

from openpmd-api.

Or we just skip the suffix at all and stay under "1.0.0" for them as simply as that.

from openpmd-api.

name all our projects without the last dot

Sure, does not bother me.

Or we just skip the suffix at all and stay under "1.0.0" for them as simply as that.

Are you suggesting we skip the suffix for CMake? I could get behind that proposal. A user would typically REQUIRE a specific version of openPMD, and would just have the latest version of this API that supports that version.

from openpmd-api.

Ok good!
I am not suggesting to skip suffixes in CMake, CMake does skip it ;-)

I will go for the following versioning as long as we are in alpha/beta state:

Is 0.1.0-alpha1, 0.1.0-alpha2, 0.1.0-beta1, 0.1.0 and then 1.0.0-rc1, 1.0.0-rc2, 1.0.0, ...
This makes package selection via CMake more transparent.

from openpmd-api.

Just so I don't confuse anything here:
The versions you listed would be the CMake versions, not the release tags?

from openpmd-api.

The release (and version.hpp) versions relate to the CMake versions as follows, since CMake does not accept suffixes in project(VERSION ...)/Config packages and skips suffixes in version parsing:

a)

b) Alternatively we could do:

• 0.1 series: initial alpha releases: 0.1.0, 0.1.1, 0.1.2, ... (non-semantic)
• 0.2 series: initial beta releases: 0.2.0, 0.2.1, 0.2.2, ... (non-semantic)
• 1.0 series: first stable openPMD standard 1.X API (semantic)
• 2.0 series: openPMD standard 2.X API (semantic)

c) or even combine the two, but that's a bit weird since the 0-1 start question a "there are only suffix releases for a version" issue come in:

from openpmd-api.

Going from that table, it appears you decided against the initial versioning idea:

to use always the same major version of openPMD-api as the base standard

Having the same X.Y.Z scheme with independent versioning will very likely become confusing.

from openpmd-api.

Do you prefer a) or b) in #87 (comment) ? I kind of tend to b).

from openpmd-api.

Thanks for the clarification! You have my blessing to enunciate the pre-releases.

Do you prefer a) or b)

Gut feeling says b, mostly for the differentiation reasons stated before.

Just thinking out loud, not entirely convinced of this myself yet:
As the semantic versioning would include suffixes anyway, we could think about StandardMAJOR.apiMAJOR-apiMINOR.DevTAG. That would make a clear distinction between standard and API. Breaking features and critical bug-fixes would then force us to increment apiMAJOR to reflect that change in CMake.

This would also mean that API version 2.1-0 could potentially not support standard version 2.1.X if the version bump happens earlier.

from openpmd-api.

Yes, my idea is very much in that direction for the stable release series: StandardMAJOR.apiMAJOR.apiMINOR

I think that's the best we can do. Too bad CMake again just has a SameMajor and no SameMinor variant for compatibility... https://cmake.org/cmake/help/v3.0/module/CMakePackageConfigHelpers.html But still.

Note: -number is kind of reserved for package build numbers of the same release (debian, conda-forge, etc.).
Note: four-number StandardMAJOR.apiMAJOR.apiMINOR.apiPatch is sometimes itchy in the Python world but at least works with CMake afaik.

from openpmd-api.

It would be amazing if we could reflect #225 in this scheme, but that dream seems to fade with the current CMake support. Version checks would happen at CMake-configure time, rather than at project compile time (i.e. comparing against version.hpp)...

StandardMAJOR.apiMAJOR.apiMINOR-TAG is probably the least awful way to go from here (at the expense of possible confusing API version with standard version).

from openpmd-api.

Don't worry about #225: I can implement that in CMake another way (added a comment therein). Of course, other packages like pypi/conda/etc. won't have that pre-selection but we can publish a table on it in the docs.

What does -TAG stand for in your example? e.g. -rc2?

from openpmd-api.