Thoughts on Python project versioning practices

[jsstevenson]

I'm proposing in this issue to use git tags to designate library versions, rather than an explicit version.py file. This is already something we do in GA4GH and biocommons projects, but it would also be a good time to take a harder look at how we are versioning things writ large. A few suggestions/topics for consideration:

drop the leading "v"

I think we mostly do this already, but might as well make it official. Historically we've used it in some places.

Pre-release designation for < 1.0 versions

Would propose that we drop this. It is particularly problematic if we accidentally don't tag certain releases as "pre-release", because then those versions become preferable for some kinds of version resolution algorithms or display interfaces (this is why the pypi badges on the gene normalizer docs are out of sync with the latest releases https://gene-normalizer.readthedocs.io/latest/). But broadly I don't think it's necessary for packages that are prior to a version 1.0 candidate -- the point of such a designation is so that users have to actively opt into the latest version, and are otherwise routed to a prior, stable version, but anything below 1.0 doesn't really have any real stability anyway. IMO if we're getting to the point of having true, stable releases on a project, we should start talking 1.0, or 1.0 pre-release candidates like 1.0a0.

Iron out our rules for < 1.0 versioning

Increasingly it seems like a lot of packages are doing roughly what ruff describes: until a 1.0 release, use the Y in 0.Y.Z to indicate a "major" version, and Z for a new minor release. In other words, any release containing an API-breaking commit (tagged with a lil !) should increment Y, and otherwise, just increment Z. Our other libraries can pin dependency ~= 0.Y.0 to just pin that "major" pre-1.0 version, and dependency ~= 0.Y.Z if we need a specific non-breaking feature that was introduced in patch Z.

I'd additionally propose that we drop most cases of dev versions, at least for releases. The Python Packaging says that it's "strongly discouraged" to do this. By default, dev versions in setuptools-scm have a particular meaning -- they represent a library state that is X git commits away from a tagged release, i.e. they correspond to an in-development state of a library, not a static, publicly-installable release. This is something that's appended automatically so if I'm working on a branch with two new commits away from a release tagged 0.1.1dev1, then the setuptools-scm assigned version would be something like 0.1.1dev1.dev2+gaER93jklDOi<more git hash>. That's configurable behavior, so it's not like it's the end of the world, but I think it does say that we're out-of-step with accepted practice on this.

Make the jump to 1.0 somewhere

Or at least: on some of our ongoing projects, come up with a "1.0 roadmap" so that we have specific benchmarks for how close we are, rather than just adding new features endlessly.

[korikuzma]

I'm proposing in GenomicMedLab/software-templates#34 to use git tags to designate library versions, rather than an explicit version.py file

I like consistency. This was also something I was thinking about when trying to make releases on disease/therapy a few weeks ago and it had failed because I forgot to update the version file.

drop the leading "v"

We could probably create a GitHub action to enforce tag names based on regex pattern (which excludes v prefix).

Pre-release designation for < 1.0 versions

👍

Make the jump to 1.0 somewhere

I think any project that has had a paper published should have a major release.

---

Overall I agree with this. I think we're inconsistent and would be nice to have rules that we can add to contributing docs or something similar.

Would be nice to leverage semantic release

[jsstevenson]

I think any project that has had a paper published should have a major release.

Yeah, we clearly should've done it for thera-py, and now it feels awkward to do it later. Maybe this would be a good place to delineate remaining expected changes (if any).

Maybe we can also start inching towards a 1.0a designation for Variation Normalizer since that one is around the corner.

[korikuzma]

Sounds good. Thanks for bringing this topic up! 🚀