Specifying versions

[waylan]

As noted in #1575, there is currently an inconsistency in the way versions are being specified which is breaking links in the API documentation to source code. This stems from differences between the release process and the version spec we use.

For many years now, we have used the Python Version Specification (originally defined in PEP 440). However, more recently we changed our changelog format to use the Keep a Changelog format. The Keep a Changelog format recommends Semantic Versioning and all of the validation tools expect/enforce Semantic Versioning.

The problem stems from a difference between Semantic Versioning and the Python Version Specification. Specifically, Semantic Versioning requires each version to include 3 components while the Python Version Specification only requires 2. In other words, while the Python Version Specification would allow 3.1 to be a valid version and even normalize 3.1.0 to 3.1, Semantic Versioning requires the version to be specified as 3.1.0 and would see 3.1 as invalid. Our code assumes the Python Version Specification and normalizes accordingly. However, to validate our changelog, the validation tools expect the 3-part non-normalized form.

This matters for the release process. Some users have insisted that in addition to uploading releases to PyPI, we also upload to GitHub (as releases, not just tags) because GitHub provides notifications that their workflows expect. One of GitHub's features is to provide release notes for each version with the release. existing tools which extract the release notes for the most recent version from the changelog expect a valid, well-formed changelog and fail when it is not valid. Before validating the changelog, most every release would fail due to some subtle formatting issue and require manual upload. Now that validation is part of our CI linters, this has not been an issue.

We have a few paths forward here:

1. Find/modify/build a changelog validator which uses the Python Version Specification for version validation.

   Thus far I have not found an existing tool which does this. And I do not have the time to do the work. So, while this would be my preferred option, I doubt it will ever happen.

   Also, some recent versions (and tags) are using the wrong version format. This would not address them.

2. Change over to using Semantic Versioning.

   While this seems simple enough for future versions, what happens to all our old versions? Not sure of the ramifications here.

   I should note that the changelog already has been changed to use Semantic Versioning and recently the release tags on GitHub are using Semantic Versioning so that they match as required by our release process. It seems that this has caused the issue noted in Make the docs build successfully with mkdocstrings-python 2.0 #1575.

3. Stop including the release notes in the GitHub releases, which would allow us to stop validating the changelog and exclusively use the Python Version Specification.

   The issue here is that some recent versions (and tags) are using the wrong version format. This would not address them.

4. Find some other method/format for managing the changelog. Not sure what this would look like.

Any thoughts?

[facelessuser]

I don't know 100% what you are looking for exactly. If all we want is to manage versions such that we never strip the "bugfix" zero, I think that is pretty easy. I've often managed my versioning myself via: https://github.com/facelessuser/pymdown-extensions/blob/main/pymdownx/__meta__.py. It would be trivial to adjust it handle "bugfix" zeros the way you desire. I don't know if you have other requirements or not. Anyway, I guess I would have to understand exact specifics what it is you are after.