There is a fair amount of complexity in software and component versioning, as well some disagreement on what is standard. Even though there are some fairly common practices across the industry, you’ll find that they don’t apply as uniformly as you’d like. Developers are usually expected to understand software versioning, even though many don’t really get their heads around it until well into their careers.

Goals of Versioning:

To communicate change.

To indicate the degree of stability of an application or component.

To communicate compatibility with a previous version.

To cross-reference to other documentation.

Software versioning is pretty easy to get reasonably right, as long as you know the basics. While there is always room for improvement, adhering to basic practices can make the process easier and less likely to end disastrously.

Episode Breakdown

Versioning Systems

19:10 Semantic Versioning

This is the main type of versioning you’ll need to know, as it is by far the most common. Version numbers are four segments, usually themselves numeric.

The segments each mean something. Major – A change here is a breaking change. A previous or next major version is unlikely to work with something that needs the current version. Minor – Changes have occurred, but are unlikely to break something. This might be a fix for something like a non-breaking security change. Revision/Patch – Changes have occurred, but almost certainly don’t break things. This might be something like a fix for wording or a spelling error. Build – Indicates a particular build. Probably not useful for anyone but the developers. This is often left off the version released to the public.

The idea here is to communicate a number of things regarding version compatibility and risk for anyone using the library or application and to do so in a standardized way. Be aware that clients often interpret these version numbers incorrectly. Sometimes you run into situations where multiple things need to have the same version number, but change at different rates

30:30 Other Versioning Structures

Semantic versioning comes from a world before continuous delivery. Sometimes the first two sections in the version number will have components of the date. For example 2018.3.11.92 would be the build for either March (or third quarter) of 2018, revision 11, build 92. You can pretty much use whichever portion of the date you want for this. Be aware that this can inform clients just how long it has been since the last version, which may not be what you want.

Some software packages just use a single version number that increments with each release. This makes it easier on users, at the expense of development and support. You can also show two different version numbers, with the more detailed one being hidden in an “About” screen somewhere. This also means that you probably should release fairly frequently, rather than relying on interim patching.

Best Practices

34:15 Producer Side

When incrementing a version segment number, zero out all the segments following it. Version only the main branch in source control. This would be the branch you release to clients. Trying to keep versions sane across multiple branches is liable to get ugly fast.

If you know that you are shipping breaking changes, then increment the major version number. If you are making big changes, but they don’t break backward compatibility, then increment the minor version number. If you are just fixing a bug and it doesn’t break backward compatibility, then increment the revision number. The build number should increment when the continuous integration server builds

44:35 Consumer Side

Read the release notes. Don’t update for a while after an update comes out. Give other people time to get burned. Obviously the above doesn’t apply if there are major security issues.

When you are consuming a library and the major version has been incremented don’t update this directly in the development branch. Instead, make a branch and update there then fix all the stuff that got broken. Then merge back into development.

When a library undergoes a minor version update, you are probably safe updating in a development branch. Just make sure you can roll back. The big consideration here is the likelihood of this sending you down a rabbit hole trying to fix it. If a particular library or framework has burned you on a previous update, treat their minor revisions like a major one.

“Trust, but verify.”

When a library has a revision change, you should be safe updating on your development branch, with some caveats. This is no time to skip reading the release notes. A little update that someone else asserts “doesn’t have breaking changes” may have subtle changes that will break your stuff. When a library makes a build update, ignore it.

There is one other thing to consider, especially if you are using a package manager due to security concerns. Be very careful about updates, especially ones that haven’t been out a while. If the publisher of a package gets breached, they could end up publishing a package that does nefarious things. This is not foolproof, however. You should also be checking release notes, running under minimum privileges, etc.

IoTease: Platform

Cayenne is a drag and drop project builder for the internet of things. Use it to create alerts, trigger events, remotely control devices, or collect and present data. It has a customizable dashboard for controlling and gathering information from your devices. While it does a lot for you it also allows for adding custom code for connected devices. They even have a Cayenne Cloud where you can build and store your APIs. The official SDKs are Embedded C, Embedded C++, and MQTT. It supports almost all of the major IoT devices.

Tricks of the Trade

Reduce the surface area of attack that you expose. There is no perfect security, but if yours is better than others, you are far less likely to get nailed unless you get someone specifically angry at you. People are mad about facebook’s foulups with privacy, but they are fine with lots of other folks having even more sensitive data. That’s because they are exposed on facebook and they know it. It hurts more when the mistake is a dumb one and the price of capitalizing upon it is cheap. Don’t be a scriptable target.

One comment on “Software Versioning”

Thank you for the informational episode Will, & BJ.
I used to like seeing semantic versioning on products but lately I’ve changed my opinion on it.
I now prefer date-based version numbers on products.

What changed my view was a JetBrains product called ReSharper, which is a Visual Studio productivity plugin.
I was able to convince my manager to purchase copies of ReSharper.
JetBrains has adopted to date-based versioning for all products.
When my manager gets a bill, he knows that the bill is for the current subscription without having to google or ask developers.

So the reason I like date-based version number is
because many products purchase decisions are made by non-technical people
and it is meaningful for them (as well as to us developers, as it reminds us to update as discussed in the episode).