RELATED: Artifacting.md
Versioning is an ancient problem, but this GIST mostly focuses on the computing era and versioning for software. This primer details a few versioning tactics along with some advisories and warnings.
Who is this for? Historically this would have been the bread and butter of the Release Manager, but these majestic creatures are long extinct. These days DevOps is responsbile for automating the SDLC, but this material can only serve to enrich anyone interested in or involved in the software industry.
Everyone's made adhoc versioning attemps at some point that failed to fulfull the intent of the effort. For example, which is the current version of this cool doc?
- cool-story.today.doc
- cool-story.new.doc
While standards such as ISO:9001, ISO 14001, OHSAS 18001, or HIPAA require document version control, they don't dictate any specification for it. So while the method applied is "AdHoc", it's generally agreed upon that DVC follows a two-segment format like: 0.1, 1.3, etc.
NOTICE: If your project is subject to any such controls, solve them early as the cost of doing so increases dramatically over time.
The most straight forward method of versioning is to iterate a number on every change. This is better in every way than using words such as "new" or "today", as obviously version 2 is newer than version 1. But that's all it communicates.
Calendar versioning is an ancient solution to this problem, and is the practice of using the date to denote when your product was created. For example:
- cool-product.1992.01.01.zip
You cannot build the product multiple times a day without overwriting previous builds, which may or may not be something to be avoided, depending on your project. If you don't care, then this is not a limitation, but many software projects have the following concerns:
- Everything is potentially releasable.
- Even deficient builds offer valuable insights.
- Overwriting previous builds eliminates the possiblity of rolling back to them.
At first glance it seems this can be overcome by simply adding a fourth segment to the version (IE: second of day, iteration), but this causes one large problem (that may not apply to your project): many tools used across the SDLC require semver compliant version numbers.
As mentioned, many 3rd party tools require a semver compliant version number. Here are some exammples:
- AWS EC2 Image Builder
- Anything that uses node-semver...
Let me know in the comments if you have other good examples.
In the event that you're adopting calver while trying to maintain semver compliance, note specifically that while calver allows for leading zeros, be aware that leading zeros are invalid in semver, and that you should use the short month/day denotation.
Don't try to squish in a timestamp into calver. The segments get too long, and inevitably some semver validator somewhere in your toolchain is going to fail it. Here's a bad example:
- YYYY0M0D.SecondOfDay.Increment
- EG: 19920101.86400.99999
All that said, calver may be right for your project. If you know that you WILL NOT have any toolchain components that require semver, go nuts. Have a look at the calver website calver.org for more on this method of versioning.
This is a highly formalized versioning scheme widely adopted by the software industry. Whether it's the best or will even be around in twenty years is arguable, but what's inarguable at this time is that the tooling for larger projects will often necessitate its use, as mentioned above.
Checkout the semver.org webiste for more on this industry standard.
Everything is potentially releasable. This is a core tenant of high-cadence software shops. One method to achieve this is ensuring that every merge into main gets versioned and built, tested, and potentially released if the tests pass.
For full CICD automation, it is required that the CI kit be able to determine the new version of the product. Early in the evolution of this posture the build/iteration number for a product was leveraged to achieve this, but this approach has largely been deprecated. There are a few common methods of iterating the semantic version of a product, such as simply incrementing the PATCH or using commit messages to signal the increment, but I don't advocate for these. Instead, checkout the GitOps Automatic Versioning Github Action.
Are there other approaches? Yes. Of course. And you're free to use any method you can think up. Just try to qualify early whether your project is going to be making use of 3rd party tooling, as in that case you'll likely be adopting semver anyhow, so it's better to start with it.
This is a solved problem. Keep it simple and just use the build number, or grab the tried-and-true, battle-hardened, off-the-shelf solution (semver) and get rolling.
EXCEPTION: If you do actually manage to out-think the entire software industry, and manage to escape the 3rd party tooling dependency on semver, take it all the way and make it the UVO of a startup.
Whatever you decide on, consider whether it'll be important to be able to sort your versions programatically (sort -V), or easily by a human.
If you truly have no dependnecy on 3rd party tools that necessitate semver, then your only consideration is your audience. in some circumstances what you're communicating to them is the critical factor. As noted at calver.org, many software projects find great success in calver, including one that I follow closely - Cockroach Labs. Checkout their article on switching to calver for more context.
Many marketing departments are used to being able to say things like "Comming this December, version 2.0...". This is fine. You can use automated versioning and make Marketing happy by simply getting the product just right on v1.x.x, and then bumping the major version.
Don't confuse versioning discrete products with a mulit-product ecosystem. While you're free to "version" an overall platform comprised of multiple services, it's more of an abstract concept. For example, your calver versioned platform may be releasing version 23.12 on the first of December, but it may simply require deploying frontend version 1.3.0 and backend version 1.80.0.
Checkout semancat versioning. This method uses cat breeds. The issues with this are that it's not semver compliant, and that the breed preceeds the calver component, complicating sorting. But again, this may not be important to your project. :)