Use semantic versioning

[faph]

With the current versioning scheme YY.N it is difficult to figure out when a release breaks the public API or not.

Could we move to semantic versioning for packaging?

Scanning through the change log, many release appear to be not breaking anything, it seems? I am using packaging in several libraries and I need to be able to specify a stable range of acceptable versions without being unnecessarily restrictive to avoid dependency conflicts.

[brettcannon]

Sorry, but we are not switching to SemVer. We chose CalVer on purpose as SemVer is not clearly defined for a language like Python (e.g., does raising a different exception count as a major/breaking change?). Plus, we want people to always at least try the latest release so as to not accidentally get pinned to an old version which doesn't get updated to latest practices (e.g., all the changes made to packaging.tags).

[faph]

I'm aware of the arguments - it all comes down what we define as the public API of a given package. That is not a Python-specific issue.

I am fully supportive of using the latest version everywhere and more or less forcing users to do so. However, that more or less renders the whole versioning meaningless. In my libraries, I would just specify something like packaging>=20.0. I may as well just specify packaging without a version.

I think it's actually funny that the "packaging" library, which defines the concept of "Version: major, minor, micro, etc", itself uses "major" as a year in an arbitrary calendar system 😄. I know, I know, it is not incompatible, but not quite a straightforward reading of what constitutes "major". The sole reason I use packaging is for its version parsing logic...

[faph]

Just one thought, to avoid silly people like me interpreting packaging's version number as semantic, would it be possible to add a note somewhere on release pages or similar?

[brettcannon]

I am fully supportive of using the latest version everywhere and more or less forcing users to do so. However, that more or less renders the whole versioning meaningless. In my libraries, I would just specify something like packaging>=20.0. I may as well just specify packaging without a version.

It still allows you to set the minimum version you need due to you relying on some new feature we add. What it doesn't let you do is let you guess at a maximum version you're compatible which may or may not be accurate since you can't predict the future. 😉 See https://iscinumpy.dev/post/bound-version-constraints/ for the philosophy behind this.

the "packaging" library, which defines the concept of "Version: major, minor, micro, etc",

To be clear, we implement https://packaging.python.org/en/latest/specifications/version-specifiers/ which doesn't define what those numbers represent. But we're pragmatic enough that we know people interpret those numbers to be "major", "minor", etc., so we have those attributes as a nicety.

would it be possible to add a note somewhere on release pages or similar?

Feel free to propose a PR for where you would expect such wording to go.

[pradyunsg]

interpreting packaging's version number as semantic

I ought to point this out...

Semantic versions are required to be "a version number MAJOR.MINOR.PATCH"¹. This project's versions are typically 2-parts, only YEAR.INDEX. Inferring them as semantic versions isn't merely deviating from this project's versioning, it's also deviating from SemVer specification as well.

At that point, the person doing this will hopefully notice that something isn't right about their mental model (as you have!). If they're assuming that a missing PATCH means 0 or something, I'm happy to say that dealing with it is not our problem to solve.

it all comes down what we define as the public API of a given package

For SemVer, I agree. For version numbers in general, I disagree. :)

The point of a version number is to communicate something to other humans who use that piece of software. SemVer assigns specific² meanings around that version number and what it would provide, and couples that with certain patterns of use that it supports/promotes/encourages. I'd argue those aren't particularly useful meanings or patterns of use for this package.

This is a foundational piece of infrastructure to the Python packaging ecosystem and, as you've noticed, we don't do things disruptively. This project's use of CalVer aligns with what the expected usage pattern for the project is -- no upper version cap, use a lower version cap to be proper, and the project as will evolve as Python standards evolve over time.

I agree that having this documented somewhere is probably worthwhile -- I wouldn't know where to put it (I'm too close to the "problem" in this instance to have clarity on where someone might look for this information).

arbitrary calendar system

Hey, it's arbitrary but useful. Wait... I'm not (just?) arguing that calendars are useful... That was a setup to link to something that this reminded me of: https://www.youtube.com/watch?v=tbqh3US6qGI (3m58s long). 😉

Footnotes

1. I'm quoting https://semver.org/ which I hope is our shared understanding of "semantic versions". 😄 ↩

2. Although, not strictly enough for some peoples' liking/understanding, as Hynek noted in a well written article. ↩

[faph]

What about a simple line like this: see #717