git-describe version style breaks dependency management

[Thomas Gilgenast]

starting in 44104d1 (with an important follow-up commit 9a470f5), the lib5c version numbers changed from PEP 440 compliant version numbers to git-describe numbering for untagged versions

this causes a bug in the lib5c version order resolution (since setuptools - and so presumably also pip - uses a PEP 440 compliant parser to order versions), which is illustrated in the following example, where the user has lib5c installed at 0.5.1-4-gecd12f9 and attempts to install a package which requires lib5c>=0.5.0:

>>> from packaging import version
>>> version.parse('0.5.0') < version.parse('0.5.1-4-gecd12f9')
False
>>> version.parse('0.5.0') < version.parse('0.5.1+4-gecd12f9')
True

only the PEP 440 version number style satisfies the requirement

the proposed fix is to switch lib5c back to PEP 440 version numbering, changing the versioneer config, re-running the versioneer install, and modifying the docker tagging procedure by adding a sed to the git-describe step.

[Thomas Gilgenast]

to some extent there is some room for debate here, specifically we can ask the question "do we only support tagged package versions when inter-package dependence is involved?"

one issue with allowing 0.5.1+4-gecd12f9 to satisfy 0.5.1 for example is that this commit may introduce a change which should make this commit belong to 0.6.0 under semver, and the depending package may explicitly require lib5c>=0.5.1,<0.6.0. in other words, dependency guarantees are more-or-less handled according to a semver contract, but without a tag to upgrade the major version, there is no already-established way by which the lib5c commit will signal to the depending packages that this commit represents an API change. this specific example of a package requiring lib5c>=0.5.1,<0.6.0 probably would never occur if 0.6.0 had not been released yet, so it is mostly contrived (though it could occur if the user installed 0.5.1+4-gecd12f9 before 0.6.0 had been released, never updated it, then 0.6.0 was released, then the depending package changed to require lib5c>=0.5.1,<0.6.0, and finally the user tried to install the depending package). more important is the general idea that dev commits may break package interoperability.

on the other hand, restricting package interoperability to only tagged versions prevents easy modification of the dependency library during development.

a compromise solution is to officially support only tagged versions and require that all commits on master be tagged according to semver contracts (so that fresh installs triggered by a dependency will honor semver by default, but dev versions can still be manually installed).

[Thomas Gilgenast]

note: this bug doesn't effect "frozen" project code that pinned specific versions of lib5c

[Thomas Gilgenast]

a sed script to replace the - with a + when injecting the version information from git describe into a Docker container is

git describe --tags --dirty --always | sed 's/-\([0-9]\)/+\1/g' | sed 's/-/\./g'

[Thomas Gilgenast]

changed version number style back to pep440

fixes #32 by reverting parts of 44104d1 and 9a470f5

→ <<cset 4e12459ca410>>

[Thomas Gilgenast]

on windows the git describe and sed combination is

git describe --tags --dirty --always | sed 's/-{[0-9]}/+\1/g' | sed 's/-/\./g'

[Thomas Gilgenast]

one important note is that I don't think docker tags can have + in them, so we will tag our docker images using git describe but keep the version style pep440

[Thomas Gilgenast]

this actually still doesn't seem to work, since for example

pip install -e /lib5c-0.5.2+16.gf83da50

seems to stumble on the + in the folder name as well, causing it to record the version (in the pip freeze format) as

lib5c===0.5.2-16.gf83da50

[Thomas Gilgenast]

reworked docker image version passthrough

the version is now recorded in the wheel, which is copied to the docker image during build instead of the source tree

this means that building the wheel is a pre-requisite for building the docker image

an alternative solution was to require that the commit be tagged before building the docker image

resolves #32

→ <<cset 5abe89763f17>>