Versioning conventions

[constantinpape]

I had a discussion with @FynnBe and @k-dominik about versioning conventions, continuing the discussions in #151.

We now decided to adopt the following pattern:

• 0.3.2-rcN for pre-releases, i.e. tentative releases where the spec changes are not ironed out yet
• 0.3.2-releaseN for releases, where release0 is the first one where the spec changes are fixed and >0 are used for code changes.

Important: we never use "bare" versions like 0.3.2, because these would have higher precedence than the -release ones, see

cc @oeway

(We should add this to some sort of developer doc)

[oeway]

Looks good! I would only add that please check if that versioning is compatible with python conventions (I believe it's https://www.python.org/dev/peps/pep-0440/), and also we need to make sure it's supported by pypi and conda.

[k-dominik]

CI is a nice thing to have - turns out x.y.z-something is not valid for conda. Conda doesn't allow for hyphens. I'm not sure I understand the semver spec correctly there - is the hyphen optional or mandatory?

[k-dominik]

Looks good! I would only add that please check if that versioning is compatible with python conventions (I believe it's https://www.python.org/dev/peps/pep-0440/), and also we need to make sure it's supported by pypi and conda.

good point @oeway - it isn't:

The canonical public version identifiers MUST comply with the following scheme:

[N!]N(.N)*[{a|b|rc}N][.postN][.devN]

in a way that scheme will also work nicely for us (and conda): we can still agree to mark

• release candidates with rc
• either we omit "bare" release like (0.3.2) here, too, but always appending post, so 0.3.2.post0 as the first "release", or we leave 0.3.2 in place.

this is not semver compliant.

>>> from packaging.version import Version
>>> Version("0.3.2.rc0") < Version("0.3.2") < Version("0.3.2.post0")
True

good enough for me :)

[constantinpape]

```python
>>> from packaging.version import Version
>>> Version("0.3.2.rc0") < Version("0.3.2") < Version("0.3.2.post0")
True

good enough for me :)

Ok, that's also good enough for me :). It's also nice that we can have the clean "0.3.2" release then.

[FynnBe]

indeed semver and PEP440 are incompatible: "Semantic versions containing a hyphen (pre-releases - clause 10) or a plus sign (builds - clause 11) are not compatible with this PEP and are not permitted in the public version field." --https://www.python.org/dev/peps/pep-0440/#semantic-versioning

it contineus with "One possible mechanism to translate such semantic versioning based source labels to compatible public versions is to use the .devN suffix to specify the appropriate version order."

but as far as I understand PEP440 "0.3.2.rc0" is not allowed. (only "0.3.rc0" would be)

[constantinpape]

but as far as I understand PEP440 "0.3.2.rc0" is not allowed. (only "0.3.rc0" would be)

I have seen the "0.3.2.rc0" pattern in other packages a lot, e.g. https://github.com/napari/napari/releases/tag/v0.4.10rc0 (although they don't use a dot ...)

[k-dominik]

afaiu the you can have an arbitrary number of integer version specifiers separated by a . (well minimum one). so even 1.2.3.4.5.5.6.2.1.22323.post3 is valid

[k-dominik]

but as far as I understand PEP440 "0.3.2.rc0" is not allowed. (only "0.3.rc0" would be)

I have seen the "0.3.2.rc0" pattern in other packages a lot, e.g. https://github.com/napari/napari/releases/tag/v0.4.10rc0 (although they don't use a dot ...)

indeed, there should not be a . before rc pep specifies the separator as optional, so both 1.rc0 and 1rc0 are valid - and equal.

[FynnBe]

afaiu the you can have an arbitrary number of integer version specifiers separated by a . (well minimum one). so even 1.2.3.4.5.5.6.2.1.22323.post3 is valid

Yes, I think so, too: "The release segment consists of one or more non-negative integer values, separated by dots: N(.N)*" I suppose they just didn't bother writnig an example with n>2...

ok, so we land on (the .postN need the dot): ...

edit: alright, so https://github.com/bioimage-io/spec-bioimage-io/issues/159#issuecomment-876497527is fine!

[k-dominik]

okay, I'll add a dot after "patch" anyway - so that we have one rule less :)

[constantinpape]

Ok, just to summarize: we have

• 0.3.2.rc1 for the release candidates
• 0.3.2 for the release with (hopefully) the stable current spec
• 0.3.2.post1 for later releases with fixes / additions to the python package

Is this correct? If yes, let's add this somehow to the docu and then close the issue.

[oeway]

Looks good!

[oeway]

I consider this is settled now.