Change version number scheme

[bgilbert]

Problem

There are several problems with the current scheme:

• When we start building Python wheels, we can't use the -nightly and -local suffixes for custom builds. The Python package version scheme doesn't allow embedded dashes, which are used to separate parts of a wheel filename.

• Soon we'll have Windows, macOS, and Linux builds, plus Python wheels of all three in PyPI. For broadly-available software, it's useful to have versions that are easy to compare, easy to talk about, and give some sense of what's happening in the package.

• The current system always names bdists after the current date (unless overridden) even when building from an older sdist. I didn't anticipate that users would actually build bdists from an sdist, but it's a completely reasonable thing to do, and we shouldn't produce surprising version numbers in that case.

Discussion

It'd make sense to base the version on the OpenSlide version number, with an added revision number similar to the package revision in distro packaging. So, the first -bin release based on OpenSlide 4.0.0 might be 4.0.0.1 and the second 4.0.0.2.

Within Python's version scheme, we might use .postN or .devN for nightly builds. .postN isn't a good fit because it's meant for official bugfix releases. .devN almost works, except it sorts before the version it's affixed to. The intention is that the base version is bumped immediately after release, e.g. 1.2.3 becomes 1.2.4.dev1, which a) requires the next version to be known and b) is not generally best practice in our (non-Python) ecosystem.

However, we could replace the dash with a plus, making the nightly or local suffix part of the local version label. This is not quite what local labels were meant for: they're supposed to indicate downstream ABI-compatible rebuilds, but "MAY be used to identify private builds created directly from the project source". But they're not a terrible fit. Helpfully, the spec requires PyPI to reject uploads with local labels.

Python sorts local version labels by splitting on dots, and then sorting each segment numerically if fully numeric, alphabetically otherwise. Numeric segments compare greater than alphabetic ones, and a local version with more segments appended compares greater than the unappended version. By putting nightly/local after the datestamp (20231102.nightly) rather than before (nightly.20231102), we can ensure that old nightly builds don't sort before new local ones. We should retain the nightly/local distinction to signal that a snapshot build is official or unofficial.

Proposal

• Official release: 4.0.0.2
• Local rebuild from official sdist: 4.0.0.2+local
• Nightly build on November 1 after official release: 4.0.0.2+20231101.nightly
• Local rebuild, on any date, from that nightly sdist: 4.0.0.2+20231101.nightly.local
  • sdists currently don't capture overrides, so this will build OpenSlide 4.0.0, not a Git revision
• Local build on November 2 from openslide-bin Git: 4.0.0.2+20231102.local
• Local rebuild, on any date, from that sdist: 4.0.0.2+20231102.local

We'd still allow arbitrary version overrides, but only of the local version label, not the 4.0.0.2 base version. sdist archives would capture the sdist version and bdists would reuse it, with a local suffix applied if not present and not overridden. As now, nightly builds would work by applying a version override in CI during both sdist and bdist.