There is a several approaches to naming a version, like hashing, date and time of release, or increment of numbers, but for some reason, semantic versioning is one of the most popular of them.

Let’s figure out what we can cook with it. But first here is a quick referance for the rules:

https://semver.org/

So, you make a company-wide policy so that engineers will now decide on the version naming.

Everyone happy! Now we have a reliable way of versioning things, right?

R-right?

Aaaannnnd… the engineer never actually followed any rules.

It’s simple, yet there is so much bias happening when you give people power to change the version.

• Architects want to reward themself for big migrations facilitated

• Devs want to celebrate big refactoring or big chunks of work done

• PMs want a major version after every epic.

There is nothing particularly bad or abnormal with people's desire to mark the big effort behind their work with a numbered version. But my points is, if you changed the whole service and no API was affected:

1. You did a great job designing APIs

2. It’s a patch change

The real-world semantic versions are ugly. And there is so much pursuit of beauty in engineering; following those rules just feels wrong, even counterintuitive.

You need to be prepared for the fact that a few years deep into the regular cadence of scheduled project releases, you will have 100+ major version changes in most interconnected and important BE services.

There is just so much professional bias happening, the faultiest, stupiddest implementation of the automatic semantic version assignment will do more reliable work than any engineer ever will.

So, let’s go back to SemVer rules.

The main idea is: will another service notice the difference if we rollback?

For example:
If another service adds a new field in their request and we have not yet introduced it in our API contract deserialization data structure, we can probably just ignore it and move on. But, getting fewer data fields than we require on the input will instantly trigger deserialization errors.

The same goes for the Response DTO; we cannot just “rollback“ the newly added field. Other services are relying on its existence! But bringing back something we freshly removed? Sure, no problems here.

We are not talking about how the internal logic of a service will react to each of these use cases; we are simply checking contract compatibility, like puzzle pieces.

I really like semantic versioning, but it only describes the public API.

If it’s not a library but a service in a structured system, I would also prefer to check the external API we use. Sooo… Let’s upgrade it a bit.

Let’s also add an answer to this question:
”What changes in our representation of the external API is backwards incompatible?”

So we can fully assess the possibility of rollback for this particular service without breaking other services or going into a downtime.

Frankly speaking, it’s the same rules for outbound traffic; they are just reversed.

Changes here have a pattern. The moment you see minor and major version changes on different sides of one API communication route, you know that backwards-incompatible changes were introduced here.

You know that without looking into the code or documentation at all!

You can also understand the direction of changes, because breach of a contract happens when a request moves from Minor → Major version change. Not sure what use you can make from that information.. But hey! To some degree, the surplus of information confirms the accuracy of the source.

So, if you try to release your services on some synchronized cycle, SemVer++ starts to describe the state of internal communication. It will also give a source of truth about service compatibility, which will help when you move towards a proactive reliability approach.

That’s how we use SemVer as a reliable tool!

Now forget about all that shit and just use Protocol Buffers.

Subscribe now

Share Reliable Engineer

This is the motto! Software release process is a tool!

To create a successful tool that will resolve company problems, you need 2 things:

1. High willingness from teams to engage with your process.

2. Grant to technical stakeholders the ability to control their part of the process.

To get the first point, you need to resolve at least one day-to-day pain from every team involved in the process:

1. Software Engineers and DevOps want to communicate with each other in their technical language while refusing to learn each other’s.

2. Product and Project managers want CLEAR ETA’s and observability over production delivery.

3. Tech support wants to know which tasks are delivered and which are not.

4. etc. etc.

For the second part, the rule of thumb is: everything that makes the process live on its own, without your major involvement, is good.

When it comes to line managers, the tooling will be complex, but if (or when) you need to involve higher and higher levels of management, the tools will become simpler and simpler.

If the line management controls will be “stop release process until blocker X is done“, the CTO level will be a big red button, “FUCK, stop everything“.

This is the way.

Subscribe now