This is part 3 of many in my “Open-source as a project model for internal work” series and the second follow up to “Empathetic Infrastructure Code Management: An Introduction”.
Departing an hour long status update meeting involving the entire development team, the department’s director asks the manager who called the meeting why he felt the need to schedule such a time-consuming event.
The manager responded, “Well, people stopped reading the email updates.”
The truth is, when you’re trying to communicate project updates, both emails and meetings are lousy methods to do it. Employees are inundated with a continuous stream of email; just ask anyone who has ever returned from a weeklong vacation and opened their inbox to 500 unread messages. And who really needs to attend yet another meeting?
The next three posts will cover three ways to communicate change that don’t require endless meetings or a continuous stream of e-mails that quickly become ignored. Instead of trying to force information on someone when they aren’t ready for it, we’ll look at how to passively communicate details “just in time”, that is, immediately when the information is actually needed.
Semantic Versioning
In the previous post, I made mention to the idea of “Semantic Versioning”. Versions are a necessary ingredient of the “pull” model of releases, as they allow different apps to use different releases. Along those lines, they also allow apps to fallback to a previous incarnation of your code if an upgrade goes poorly.
There is quite a history of versioning schemes out there, from the simple incremental number that most movie sequels follow (Think the Rocky movie series) to complex schemes that don’t make much sense, like what Microsoft Windows has done:
Credit: https://twitter.com/sosowski/status/517005067334205441
Some open-source projects version by date of release. If you look at the Ubuntu release history, you’ll notice they all follow x.04 or x.10. This relates to them following a 6-month release cadence, with releases occurring in April and October.
The problem with these schemes is that they don’t tell you much about what’s going on, except that it’s a different version. And while version numbers can be fun for marketing to toy with, a smart versioning system gives real information to the user.
I personally prefer the Semantic Versioning model defined by the co-founder of GitHub and used by Node.js, io.js and many of the modules built for the two. It strongly defines how versions are to be incremented, and helps to communicate the type of change with each version update.
Semantic versioning designates three numbers to a release. In order, the major, minor and patch number (e.g. major.minor.patch). With actual numbers, that looks something like 0.1.0 or 2.13.2.
The major number is only updated when you make incompatible API changes.
The minor version is updated when you add functionality in a backwards-compatible manner.
A patch upgrade happens when you make backwards-compatible bug fixes.
As a consumer, when I see a project version change, I know one of the following three things:
- A change in the patch version tells me Trust, but verify. Make the update planning for little to no work, but do run a regression tests as always.
- A change in the minor version tells me to expect a little bit of work. Maybe dedicate an afternoon to getting things up to date.
- A major version change tells me to plan an entire cycle for the upgrade. It will take a lot of work, but it normally brings a much greater benefit than other version changes.
All of this is done without a single word being said or typed. The consumer intrinsically knows what to expect from only a few numbers.
This little bit of structure goes a long way in making sure that consumers are aware of what’s going on with a project, without them having to bother you about details or search their inbox or try to recall the details talked about in a meeting two weeks ago.
As always, no code or best practice is magic. For a rebuttal on Semantic Versioning, there’s some good discussion going on in this thread (with rebuttals to the initial rebuttal).
Despite it being tricky sometimes to know which number to upgrade, I find that overall it can be very meaningful. Just because it requires a little bit of thought and effort to get right doesn’t mean it should be thrown out. Everything meaningful requires work.
Interested in more? Subscribe to the newsletter to recieve update when a new part in this series is published and for other related information.