Over time I become more and more fond of calver, I can never remember arbitrary version numbers even for my own software.
Roughly remembering the state of the project at a specific point in time is often much easier, and it’s also often easier to backtrack problems & incompatibilities.
Very hard to give up SemVer though, especially before 1.0.
Fun thing is that “calver” in french (“calvère” more precisely), defines something hard to deal with, because it is too complex or messy.
Jokes aside, my main issue with CalVer is that you can’t easily see the “milestones” of a project, eg when the API changes a lot, whem it reaches a stable state, or when it gets rewritten, etc…
If you take the Ubuntu example, there is no distinction between LTS and standard releases.
Same with youtube-dl, I was using a version from early 2017 for monthes, and then google changed the youtube API and youtube-dl had to accommodate, making all previous releases useless. You can’t know which version address that other than reading all changelogs in between.
I like more the way softwares like “pcc” are handled, with a SemVer mode, and daily builds (or weekly/monthly) whatever, that help you get the build tree at a specific date if you so prefer.
Best of both worlds!
At work we use YYYY.MM.NN for internal software (NN being a 0-indexed release number for that month).
I like this for knowing when something was last updated, but it’s not helpful for identifying major changes vs. bugfixes. Perhaps that’s not such a big deal for software that’s on a rapid release cycle.
It’s also not a big deal for software that’s too big or complex for “major change” to be meaningful. If a tiny, rarely used Debian package removes support for a command-line flag, that’s a major change (in the SemVer sense) and since Debian includes that package it’s therefore technically a major change in Debian. But if Debian followed SemVer that strictly, its version number would soon leave Chrome and Firefox in the dust, and version numbers would cease being a useful indicator of change.
Isn’t Debian’s solution to this to not include major-version changes in updates to an existing release? So it does wait for the next major version of Debian to be included, usually
It’s why we have to make “stable” releases. Otherwise everyone goes crazy. If someone is updating their SemVer too often, they have bad design or do not care for their developers.
The concept of breaking changes in a public API isn’t really related to ‘read the docs’, except when it comes to compiled in/statically linked libraries.
If you have dependency management at the user end (i.e. via apt/dpkg dependencies that are resolved at install time), you can’t just say “well, install a version that will work, having read the docs and understood what changes when”.
You instead say “I require X major version of package Foo”, because no matter what the developer does, Foo version X.. will always be backwards compatible - new features might be added in a X.Y release, but thats not a problem if theyre added in a backwards compatible manner (either theyre new functionality that has to be opted in for, or e.g. they don’t require extra options to work).
Yes, I know that things like Composer and NPM have a concept of a ‘lock’ file to fix the version to a specific one, but that’s not a solution for anything but internal projects. If you’re installing tools that you aren’t directly developing on yourself using NPM or Composer, you’re doing it wrong.
I really don’t see what that has to do with the linked thread. In the very first line, you mention a “public” API. The point is that there’s much less consensus on what constitutes a public API than developers assume. So, you end up having to write/read the docs about what would constitute a “semantic” version change. (Not that docs are a silver bullet, they’re just a necessary part of healthy software development.)
The point is that there’s much less consensus on what constitutes a public API than developers assume.
A comment by you making that same claim on GitHub isn’t really evidence of a lack of consensus. What possible definition is there for “public API” besides, “something that will be consumed my someone outside the project”.
So, you end up having to write/read the docs about what would constitute a “semantic” version change.
The decision tree for SemVer is two questions, with 3 possible outcomes. And you’ve still ignored my point. Adherence to semver means you can automatically update dependencies independently of the developer.
So, for instance, if the developer depended on a shared library, that happens to have a security vulnerability, when the library author/project releases a new patch version, end-users can get the fix, regardless of what the tool/app developer is doing that week.
As for your closing comment, I’m noticing an important assumption I’m working to uproot: current date is not the only possible date in the release version. manylinux2010 came out in 2018, and is named as much because it’s backwards compatible to 2010.
The Teradata example on the CalVer site also highlights maintaining multiple releases, named after their initial release date. At the consumer level, Windows 98 got updates for years after 2000 came out.
That isn’t a failing of semver, it’s a failing of the developers who didn’t properly identify they had a breaking change.
The same thing would have happened under calver, they would have marked it as a patch release with compatibility to the previous version, regardless of the date component.
Expecting people to just forget about the possibility of automatic dependency updates is like suggesting people forget that coffee exists after they’ve had it daily for 10 years.
By coincidence, I just today saw that CentOS does almost exactly what I was going to propose here: use a version that mixes a standard version number with a date:
7.1.1503 indicates major version 7, minor version 1, released in 2015-03.
Over time I become more and more fond of calver, I can never remember arbitrary version numbers even for my own software.
Roughly remembering the state of the project at a specific point in time is often much easier, and it’s also often easier to backtrack problems & incompatibilities. Very hard to give up SemVer though, especially before 1.0.
Fun thing is that “calver” in french (“calvère” more precisely), defines something hard to deal with, because it is too complex or messy.
Jokes aside, my main issue with CalVer is that you can’t easily see the “milestones” of a project, eg when the API changes a lot, whem it reaches a stable state, or when it gets rewritten, etc… If you take the Ubuntu example, there is no distinction between LTS and standard releases. Same with youtube-dl, I was using a version from early 2017 for monthes, and then google changed the youtube API and youtube-dl had to accommodate, making all previous releases useless. You can’t know which version address that other than reading all changelogs in between.
I like more the way softwares like “pcc” are handled, with a SemVer mode, and daily builds (or weekly/monthly) whatever, that help you get the build tree at a specific date if you so prefer. Best of both worlds!
At work we use YYYY.MM.NN for internal software (NN being a 0-indexed release number for that month).
I like this for knowing when something was last updated, but it’s not helpful for identifying major changes vs. bugfixes. Perhaps that’s not such a big deal for software that’s on a rapid release cycle.
It’s also not a big deal for software that’s too big or complex for “major change” to be meaningful. If a tiny, rarely used Debian package removes support for a command-line flag, that’s a major change (in the SemVer sense) and since Debian includes that package it’s therefore technically a major change in Debian. But if Debian followed SemVer that strictly, its version number would soon leave Chrome and Firefox in the dust, and version numbers would cease being a useful indicator of change.
Isn’t Debian’s solution to this to not include major-version changes in updates to an existing release? So it does wait for the next major version of Debian to be included, usually
Yep, and this is where the
-backportsor vendor repos are really useful - newer packages built against thestablerelease.It’s why we have to make “stable” releases. Otherwise everyone goes crazy. If someone is updating their SemVer too often, they have bad design or do not care for their developers.
There’s a discussion of CalVer and breaking changes here: https://github.com/mahmoud/calver/issues/4
Short version, “public” API is a bit of a pipe dream and there’s no replacement for reading (and writing) the docs :)
The concept of breaking changes in a public API isn’t really related to ‘read the docs’, except when it comes to compiled in/statically linked libraries.
If you have dependency management at the user end (i.e. via apt/dpkg dependencies that are resolved at install time), you can’t just say “well, install a version that will work, having read the docs and understood what changes when”.
You instead say “I require X major version of package Foo”, because no matter what the developer does, Foo version X.. will always be backwards compatible - new features might be added in a X.Y release, but thats not a problem if theyre added in a backwards compatible manner (either theyre new functionality that has to be opted in for, or e.g. they don’t require extra options to work).
Yes, I know that things like Composer and NPM have a concept of a ‘lock’ file to fix the version to a specific one, but that’s not a solution for anything but internal projects. If you’re installing tools that you aren’t directly developing on yourself using NPM or Composer, you’re doing it wrong.
I really don’t see what that has to do with the linked thread. In the very first line, you mention a “public” API. The point is that there’s much less consensus on what constitutes a public API than developers assume. So, you end up having to write/read the docs about what would constitute a “semantic” version change. (Not that docs are a silver bullet, they’re just a necessary part of healthy software development.)
A comment by you making that same claim on GitHub isn’t really evidence of a lack of consensus. What possible definition is there for “public API” besides, “something that will be consumed my someone outside the project”.
The decision tree for SemVer is two questions, with 3 possible outcomes. And you’ve still ignored my point. Adherence to semver means you can automatically update dependencies independently of the developer.
So, for instance, if the developer depended on a shared library, that happens to have a security vulnerability, when the library author/project releases a new patch version, end-users can get the fix, regardless of what the tool/app developer is doing that week.
The automatic updates work until they don’t. Here is a recent example where Python’s pip broke with many assumptions about public APIs. Your point has not been ignored, I’ve written about it extensively, in the linked thread and in the linked site (and links therein).
As for your closing comment, I’m noticing an important assumption I’m working to uproot: current date is not the only possible date in the release version. manylinux2010 came out in 2018, and is named as much because it’s backwards compatible to 2010.
The Teradata example on the CalVer site also highlights maintaining multiple releases, named after their initial release date. At the consumer level, Windows 98 got updates for years after 2000 came out.
That isn’t a failing of semver, it’s a failing of the developers who didn’t properly identify they had a breaking change.
The same thing would have happened under calver, they would have marked it as a patch release with compatibility to the previous version, regardless of the date component.
Expecting people to just forget about the possibility of automatic dependency updates is like suggesting people forget that coffee exists after they’ve had it daily for 10 years.
By coincidence, I just today saw that CentOS does almost exactly what I was going to propose here: use a version that mixes a standard version number with a date:
7.1.1503 indicates major version 7, minor version 1, released in 2015-03.
https://en.wikipedia.org/wiki/CentOS#Versioning_and_releases
it’s curious that people seem to only consider user facing problems of semver and never consider internal dependencies.
CalVer is great for user-only software (such as Ubuntu or youtubedl) but terrible to pin to for a specific internal API.