-
jamesog
3 months ago
|
link
| on:
CalVer: A software versioning convention that is based on a project's release calendar
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.
-
-
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.)
-
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.
-
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.
-
-
-
-
-
-
-
My first gut reaction: if you find yourself reaching for
glom, refactor your data into something simpler so you don’t have to use it.I mean sure, there are some domains and use cases where it could be warranted, but the page tries too hard to sell it as a long-needed solution for a ubiquitous problem. Which it isn’t.
-
-
-
Maybe I’ve just been unlucky with the data I’ve worked with, but LinkedIn, Facebook, GitHub, Wikipedia, Twitter, and PayPal’s APIs (especially the midtier/internal ones) are all exceedingly nested. Could just be my experience, but nested data seems pretty ubiquitous to me!
-
-
It’s worth taking a look at the author’s projects page, it’s a treasure trove of well engineered Python modules.
-
Thanks! In fact, this comment led me to update it. Long overdue, it has over 20 projects now: http://sedimental.org/open_source_projects.html :)
-
-
You forgot to point out that Python provides a traceback:
Traceback (most recent call last): File "smalldemo.py", line 17, in <module> main() File "smalldemo.py", line 8, in main bar(target) File "smalldemo.py", line 11, in bar foo(target) File "smalldemo.py", line 14, in foo value = target.a['b']['c'] KeyError: 'b'And the varying error messages it gives is enough to pinpoint which one of these operations failed.
It looks like a good exercise project though. Someone saw time to work out the documentation and it didn’t fail entirely explaining what this thing is doing. Good exercise especially for the purposes of explaining what’s the purpose of that thing. It can get tricky.
-
EDIT I just realized that you were referring to the author’s statement about which dict get is causing the error. My statement below is not relevant to that.
The traceback is good, but if you are getting lots of deeply nested json documents some fields might be present on one document and not on another within the same collection. So you end up in this loop where you process a piece of the collection, hit an exception, stop and fix it. Repeat this a while until you think the code is stable. Then at some point in the future you end up with another piece of a new collection that blows up. C’est la vie.
-
Trust me, no forgetfulness occurred here. If
'b'and'c'were variables, which they commonly are, you wouldn’t know which one had the value which caused the KeyError. And furthermore, the example was more about the TypeErrors, such as the one raised when a dictionary is replaced with a list.The traceback sheds no light on that. The only way to make the traceback work is to split up the operation into multiple lines, and that’s why that code ends up verbose and un-Pythonic.
-
https://sedimental.com – My essays on Python and software https://pythondoeswhat.com – Python tricks and oddities