Informatik Handwerk
Peter Fargaš
Programmer :: Prototyping, Research
PHP | JavaScript | Java
Informatik Handwerk
Peter Fargaš
Programmer :: Prototyping, Research
PHP | JavaScript | Java
Informatik Handwerk
Peter Fargaš | Programmer :: Prototyping, Research | PHP,JavaScript,Java
Release date: February 2021
Link to authoritative version

I Have No Use For Semantic Versioning Yet

A standard is often a fine thing,
but even if it would be perfect,
it ain't of no use,
if one is using it wrong.

Major Number?

Why won't just give the product a new (name)space. And keep the old one included. It solves so many problems, believe me.

If you do not change the namespaces of the parts where the semantics(=API) of the methods has changed, even slightly, you are spawning, if not problems, at best intransparencies on your clients side. If you overlap the old with something new, everyone just got blind.

Minor Number: What is an API?

Is it something like the signature of namespaces, of classes, of methods? Not quite. API carries the description of what it's parts do. Hidden behind a crude documentation with quite some silent assumptions, is a fine structure of control flow and data typing. In the worst case, a bugfix can have influence on it. If your tests do not cover all cases, if you commit a change to your tests - there is no way to make that promise, that the API did not change. Stable API - that is just a best-effort service, no guarantees can be given.

And hey, there is this other side. API's change. Evolve. And that is a good thing. I think there is a quite clear cutting line, between having an unskilled architectural design, an API which needs overhaul all the time, and moving on to something objectively better. Let us call things by their real name - those users, which do not have capacities to tender their gardens, are exerting pressure on products, to continue with a suboptimal design? So there is that balance. Were we just forced there to bump up major number? Just spawn a new namespace.

Collisions: 1.0 You Are (Not) Alone.

SemVer does not talk about dependencies. But it is an important point. The more dependencies a project has, the tighter the mesh of version constraints. And in this tight mesh, one replaces something, with something different, having the same name? How is that supposed to work?

If you would pay close attention to how the libraries update, you will notice, that sometimes, an update of one library is just not possible, because some other is blocking it. The update procedure gracefully skips over that - and maybe weeks later, the other library lifts it's version constraints. Eventually update happens, without you even noticing, that there was that blockage. It might happen, that a stale development freezes larger and larger parts of your dependencies, so being attentive is a good idea.

Many tools come bundled with the libraries they use, because there is high chance, they would disrupt the landscapes they operate on when using shared space. They have their libraries with prefixed namespaces, which decollide them.

Patch Number

Finally, this makes sense. Translate those git hash commits into a simple, human memorable succession.

What is happening there

While people uncover the actual properties of the new version, the version number completes it's meaning. You cannot do it the other way round, you can only suggest it. It is the other direction of flow of time.

Strange Anomaly: When I do this, I could get by with just the patch number.

And so every time I need to change the API, I clone things into a new namespace, do my new things there and keep the old API as it was.

I have a \ihde\v3_0\exception namespace, an \ihde\v4_0\exception, \ihde\v4_1\exception and a \ihde\v5_0\exception also. They all coexist fine and why shouldn't they? In projects where I use those library, I often end up using multiple variants, as I just work myself through. As far as the design allows it, naturally. Having both the old and the new at disposal, gives so much more breathing space.

Thus I do evolve API, without having to change the minor number. Because I keep the implementations next to each other, instead of awkwardly replacing one with another. Noone is magician enough, to pull that off. Just give the new things new space. Obviously, namespace is sometimes not all there is to make it. But often, that is all it takes.

Other recommendations?

So I give namespaces a version number and classes also get a version suffix. When I upgrade, this helps me highlight all the usages and I get the update issue in full detail into git.

If possible, provide your users with automated update procedures. For me the sequence goes like this: "patch keeps working without intervention", "minor upgrade is automatizable", "major needs manual attention". Maybe that is what SemVer was supposed to be.

I knew I wanted to evolve my codebase flexibly, it could not have taken more then half an hour of thinking and I am using this system for years now. If you want to spend another hour of your time, on someone convincing you that it is a good idea, here is a talk you might like: Spec-ulation Keynote - Rich Hickey(youtube)

No comments yet.