autover compared to setuptools_scm

[enkore]

• How does autover's approach differ from setuptools_scm?
• When would autover be preferable over setuptools_scm, or vice versa?
• (How do you use autover? There is no real documentation.)

[ceball]

Unfortunately we have not yet documented autover; we are still rolling it out across our own projects.

autover was created to replace versioneer in our own projects, after evaluating that versioneer and alternatives were unsuitable for our own particular use case. I'm not sure if the evaluation has been recorded, but I agree it would be a useful thing to make available (I think there are many choices in the space, with various trade-offs).

[ceball]

Sorry not to answer your questions (which are good questions!), but your question's prompted me to record various versioning tools I know about. I guess our docs should include comparisons with some of the following (possibly categorizing the various alternative approaches, because they probably fall into a few different groups):

• versioneer (https://github.com/warner/python-versioneer)
• setuptools_scm (https://github.com/pypa/setuptools_scm)
• auxlib (https://github.com/kalefranz/auxlib)
• a do-it-yourself approach (e.g. techniques listed in https://packaging.python.org/guides/single-sourcing-package-version/)
• pbr (https://docs.openstack.org/pbr/latest/)
• incremental (https://github.com/twisted/incremental)
• bumpversion (https://github.com/peritus/bumpversion)
• changes (https://github.com/michaeljoseph/changes)
• zest.releaser (http://zestreleaser.readthedocs.io/en/latest/)
• rever (https://regro.github.io/rever-docs/)

Some of those do more than just versioning. (And I'm sure there are more I've forgotten...)

[jbednar]

That's a useful list. Given how long it is, my suggestion would be to take our list of very-strict criteria that we had when looking for a versioning system, and make a matrix showing which tools support which of those criteria. It's ok for a given cell in the matrix to be blank (not known), but in many cases we do know whether the tool supports what we need, and in each case there was at least one major omission that made the tool unsuitable for our purposes. E.g. criteria like "adds only a few lines of code to a new project's repository", "provides a meaningful version under condition X" (where we have a long list of conditions X), "can be embedded without introducing any dependencies to the project", "supports automatic releasing on a git tag", etc.

[maximlt]

cc @jlstevens @jbednar

Reviving this old discussion as I've started to look at how to fully convert the HoloViz projects to pyproject.toml and getting the project version is one of the parts that is not straightforward as the version is not static data, at least not how we define it based on autover/param.version (I assume some people just stick it in there).

To keep on using param.version as the tool that takes care of the projects versioning it would need some modification. I think that we would need to create a function that sets the version on the setuptools Distribution via the setuptools.finalize_distribution_options entrypoint.

Before any change like that is done, I wanted to check whether there was an alternative out there that could be a good candidate to replace param.version. For that, I would need to know what motivated developing it, i.e. what features it added support to that other tools didn't have at the time? It'd also be good to check whether we still need these features? With that information, I could start having a look around to see whether that replacement tool actually exists.

The landscape of versioning tools is pretty wild and users seem to have very strong opinions on how it should be done. I personally really don't have any, so to those here who do, please chime in and enlighten me! That would greatly help.

A good source of information is this page on the documentation of setuptools-git-versioning, which is yet another versioning tool, that appears to be quite complete and that is used by Bokeh.

[jlstevens]

For that, I would need to know what motivated developing it, i.e. what features it added support to that other tools didn't have at the time?

The ability to tell you a version without having to add tens of thousands of lines of impenetrable (and horrific if you actually try to understand what it is doing!) code to your codebase.

That said, I've given up on sanity so you are welcome to switch to whatever other (almost certainly insane) tool you prefer! Maybe there is something good now since autover was created, I still despise versioneer but I've come to the conclusion that I will put up with it, as long as I never ever need to look at it or touch it in any way.

You would think that generating a version string is a simple task, but like many things in python packaging, it is just another path to madness :-)

[jlstevens]

If you were to switch to another tool, here are a few main things that I think are mandatory:

1. Git tag based versioning (i.e. compatible with our entire release workflow in CI)
2. We don't want to change our versioning scheme for any of our project. We use semver and the tags have the prefix v
3. We are supposed to be able to get information about which commit is being used for developers who aren't on a tag. Typically, this is done using the output of git describe.
4. Supposed to work with git archive e.g. for pip+git installs though I don't know what the priority is for this.

I would be very happy if we could find something to replace autover that satisfies our needs, but I am not hopeful. The default alternative is to use versioneer just because it is commonly used elsewhere (horrible as it is).

[jlstevens]

The 'classic' vendored mode of versioneer is all that existed when autover as created but now there is now a 'build-time' dependency mode. I find this new mode is a lot less obnoxious conceptually but I don't like the fact that it is described as 'experimental'.

[maximlt]

If you were to switch to another tool, here are a few main things that I think are mandatory:

1. Git tag based versioning (i.e. compatible with our entire release workflow in CI)

2. We don't want to change our versioning scheme for any of our project. We use semver and the tags have the prefix `v`

3. We are supposed to be able to get information about which commit is being used for developers who aren't on a tag. Typically, this is done using the output of `git describe`.

4. Supposed to work with `git archive` e.g. for `pip+git` installs though I don't know what the priority is for this.

Thanks, that's a very useful list!

The default alternative is to use versioneer just because it is commonly used elsewhere (horrible as it is).

I actually seriously doubt that. I don't see it being used much, particularly not in new projects. At about 150k downloads/month on PyPIStats, compared to e.g. 16M downloads/month for setuptools-scm, I believe it's just old tech at this stage.

[jlstevens]

At about 150k downloads/month on PyPIStats, compared to e.g. 16M downloads/month for setuptools-scm, I believe it's just old tech at this stage.

Good to hear!

I know nothing about setuptools-scm so I would love to hear your thoughts (and whether it can do the things we want).

[philippjfr]

I actually seriously doubt that. I don't see it being used much, particularly not in new projects. At about 150k downloads/month on PyPIStats, compared to e.g. 16M downloads/month for setuptools-scm

I think this is at least partly an artifact of how these solutions work. Versioneer for the longest time worked via vendoring, i.e. while setuptools-scm gets installed every time someone builds the package, versioneer is vendored into the library only once. These days versioneer supports both. The overall point that setuptools_scm is the recommended and canonical approach is true though.

[jlstevens]

Right!

The download stats are probably because the projects using versioneer have vendored it in.

These days versioneer supports both.

I noticed Bokeh doesn't seem to have a versioneer.py - I was wondering if Bokeh is now using the newer approach and whether you have any opinions about it being described as 'exprimental' in the README?

[philippjfr]

Bokeh switched to setuptools-git-versioning last August. Worth looking at their build infrastructure modernization PR in general: bokeh/bokeh#12306

[jlstevens]

Ok, this docstring is outdated then.

[jbednar]

setuptools_scm does seem worth evaluating; if it could replace autover, I'd be happy to forget autover existed! The main criteria are listed in my comment above; I was only meaning to list examples of the criteria, but I think those are actually the important things.