Ragzouken
commented
1 week ago Sounds sensible (basically SemVer? https://semver.org/).
nanover-protocol is split into several packages (https://anaconda.org/IRL/repo) but I think it's assumed you will only ever install nanover-server which is a dummy package dependent on all (I think) of the others. Right now they all use the exact same version number, which is convenient and doing otherwise seems like a lot of trouble.
Currently versions are generated when the CI publishes (https://github.com/IRL2/nanover-protocol/blob/main/.github/workflows/conda.yml) with echo NANOVER_BUILD_VERSION="0.1.$(git rev-list --count HEAD)" >> "$GITHUB_ENV" which is then picked up in each package (e.g https://github.com/IRL2/nanover-protocol/blob/main/python-libraries/nanover-ase/conda/meta.yaml)
So right now the version is always 0.1.[number of commits] -- is there a better place for that 0.1. to live than the github CI yaml?
Proposed versioning is as follows:
The patch_version is for small bug fixes and features that have no impact with respect to API compatibility. Thus clients of a given major/minor version should be able to pick up new patch versions and expect existing functionality to work in a compatible way. Patch_version may be implemented as the number of commits to the Nanover_protocol main branch since the last minor version or as a UTC date-time stamp of the corresponding CI build on main .
Minor versions represent a significant upgrade to the protocol (with respect to number of issues fixed, new features etc.) still maintaining backwards compatibility for clients using earlier minor versions (within the same major version). So clients using, for example, Nanover-protocol version 1.2.x should be able to upgrade to version 1.3.y and expect API compatibility.
Major versions represent a significant upgrade to the protocol and may break API compatibility (for example by removing APIs that were deprecated in earlier major versions). Within a major version, APIs may be deprecated but still supported until the next major version.
Thus a client upgrading from, for example, version 1.3.x to version 2.0.y may experience API incompatibility will be documented (either as deprecation warnings in the earlier version) or in the upgrade documentation for version 2.0.
In general clients should be able to upgrade to any minor version within a major version (without upgrading to intermediate minor versions) without breaking API compatibility.