From: wayne+blog@waynewerner.com To: everyone.everywhere.all.at.once Date: Thu, 12 Feb 2026 17:23:26 -0600 Subject: How I Version
How I manage numbering my software versions.
Versioning is hard. The number of words that have been written over the decades
probably numbers in the millions. We've probably all experienced the challenges
of versioning. How many of us have seen files like
2023-05-15-report-final-FINAL-v2-copy-copy(2)ACTUALFINAL.xlsx? Software
versions are just as ridiculous. Maybe even moreso. Because what does
2.123.4.1.dev3.rc42 really mean?
I mean, what does 3.2.0 or Windows 11 even mean?
The first approach that I saw where versions are better is to use SemVer. SemVer formally defines what each of these numbers mean. In SemVer, the numbers mean MAJOR.MINOR.PATCH. It gives your consumers a way to understand that you did (not) change something. When you make a breaking change, you increment your MAJOR number, your MINOR number is for adding backwards-compatible features, and your PATCH number is just for bugfixes. The only problem with this is that versions are still a lie. We don't agree on what these things mean. Is a long-standing bug that people rely on getting fixed a major or a patch change? Even something as minor as changing how strings are handled can have lasting, far-reaching complications.
So SemVer alone is just not going to cut it.
I use CalVer and Keep a
Changelog with YYYY.MM.PATCH, which
has so far been the perfect combination for me. Sometimes I use YY if I want
a shorter initial number. This three segment format, as far as I know will work
correctly for all platforms. Some of them get testy if you try to do
YY.MM.DD.PATCH, so I skip the day, since I will often release a few times in a
single day. For Python packages I'll also include
pre-release or dev
specifiers like
.dev1 or rc1.
This handles the computers. They can split on the periods and know which release is newer. But we still need to communicate with each other. For that, I use Keep a Changelog. As it turns out, humans are the people who consume and use software. I know, shocking - you would think that software is for computers since computers run the software, but it's actually for humans, because humans are the ones seeking the outcome. There's a saying, "People aren't buying your drill to have a drill, they're buying the holes that your drill makes." The same thing is true about any software you write.
People don't care what your software is. They care what your software can do for them. Maybe it saves time, maybe it drills holes, maybe it tracks the changes to the text that they've been writing that just might correspond with source code that can be executed.
And the only way to communicate with humans is with language.
Trying to encode language into 3.14.1 -> 3.14.2 loses far too much information. That's where a solid Changelog comes in:
# 3.14.2 - [Released 2003-14-13]
## Added
- Cool new feature! Use it with `--cool` flag!
## Changed
- Backing database is now sqlite instead of flat text file.
## Deprecated
- `--blarg` flag has been deprecated in favor of `--quux`. A warning will be
emitted until removal on or after 2004-14-13.
## Removed
- Removed `--fnord` flag (deprecated in 2.10.0). Use `--FNORD` now.
## Fixed
- `--boop` no longer accidentally deletes `.boop` files when `/tmp/fnord/`
exists.
Naturally a Security changelog should be the only thing, e.g.
# 4.2.13 - [Released 2004-02-01]
## Security
- Fixed vulnerability where someone can put their left foot in, then their left
foot out, and shake it all about to gain root access. See
<https://security.example.com/hokey-pokey> for more info.
Whoever consumes your software; whether that's another developer, or an end user, they can read your changelog and know what they need to know. If you only have additions, there's probably nothing they really need to worry about. They should be able to upgrade. Changes, removals, or deprecations? Well... there might be something that they want to take advantage of there.
And naturally, they'll want to pull security fixes ASAP.
It takes some work -- you have to maintain your changlog somehow, and ensure that it's published. But you should be doing that kind of thing anyway so it's really not a huge lift. And if you can't explain the change that you've made in these kinds of terms then you probably don't really understand the change that you've made.
But like... this all works.
CalVer + Changelog tells people everything they need to know about your software:
I haven't found a better approach to versioning software. And if your versions are just guesses right now, maybe you should give it a try.