I have worked with many teams and developers in various capacities. I have seen a wide spectrum of problems, a wider spectrum of solutions, and an even wider spectrum of proposed solutions, and in these problems and solutions, there are a few that, seemingly, just never get nailed down. Today I’ll discuss one: versioning.

Yes, versioning. I know it sounds crazy, but for some reason, time and again, this topic continues to elude even the most competent of teams. And, no, I’m not talking about “marketing version.” You’re marketing team has a different set of problems that they are trying to solve. So, if they are calling your version v2.3.5, version 4.0! That’s great — Let it go. Here, we are interested in our development workflow and managing codebase qualities and feature-set compatibilities. So, our versioning isn’t just some tag line to move product off the shelf. Our versions should be thoughtful, informative, intelligent and valuable.

The versioning system that we will look at today, is nothing earth-shattering or new. It is just an attempt to highlight the whats, whys and hows of a system that I use, and find to be very straightforward, insightful, smart, and simple. This versioning system is tied to your VCS or SCM fairly tightly, as it really pushes the VCS/SCM to  maintain this information for you. This is not “the only” or “the best,” or “the correct” solution. It is, simply, a straightforward, informative  system that works.

The System

This versioning system requires 4 numbers separated by dots and two preceding characters: cc#.#.#.#, or a match to the following: /^(?:[vb]|rc)(?:\d\.){2,3}\d$/ (<- Gratuitous regex nerding.) :{)}

The rules for these components are as follows:


The characters may be “v,” “rc,” or “b.”

A “v” indicates that the version went to prod. It may or may not still be live, but, nonetheless, there was a time in it’s life where that snapshot of the codebase was in a production environment.

An “rc” indicates that the version is a release candidate. This means that it is a version that, after development and testing, we believe is the snapshot that will go live and become a “v” version. This version will be released to a testing environment for all stakeholders to review, and upon successful review, be released and tagged as a “v” version.

A “b” indicates a version that is either a patch for a current critical production bug, or an RND initiative that may or may not go live.


The numbers can be any number from 0-MAX. To discuss them I will introduce the following format: M.m.b.i, where each letter represents a number in the versioning system.

M => (Major) : This number indicates that the corresponding codebase has a defined set of features and a public API. A disparity between different versions at this level indicate that the versions do not necessarily support congruent public APIs and that dependent projects will likely require updates to their dependent codebase upon update. Different Major versions are allowed to cause breaks, introduce side-effects or produce unexpected results in dependent codebases switching between Major versions.

m => (Minor): A disparity between versions at this level indicates that the codebases differ, but that dependent codebases could still use either version. That is, a disparity here indicates backward compatible changes. The public APIs and return values of legacy members will remain intact, but there may be internal optimizations, refactors, new patterns, or even new features and new APIs introduced. All of these, though, will not have any adverse effect on projects that are dependent upon a previous version that has a equivalent Major version number. This number is reset to zero when the Major version is incremented.

b => (Branch): This number can indicate a few different scenarios. It could indicate a version that includes critical patches for a buggy prod version. It could also indicate a version that contains an RND set of features that may or may not be included in a future version. This number is reset to zero when the Major version is incremented.

i => (Iteration): This number is a development version indicator that is great to use in a workflow that includes marking release candidates. Though the release candidate concept can be quickly and easily abused and cause a stalemate to go-live, we will not discuss that here. Used responsibly, release candidacy paired with good management can free up the codebase from potential dev locks as release date approaches. This number is rest to one when the Major or Minor version is incremented. This number also may or may not follow to the prod version depending upon your version control management standards. Many times the iteration number is dropped when the final release candidate is chosen and tagged after go live. Proper tagging will  retain the release candidate information in the version control history.

In Practice

Obviously, this system, as with any other, has a veritable n-1 possible scenarios in practice, but there are a common set of questions that you can ask yourself in most of them to determine what your version should be. That said, let’s look at one contrived example and ask ourselves the questions to see how this works.

Let’s say that we are on an Agile dev team. We work on an eCommerce site for some retailer; more specifically, we manage the point-of-sale (POS) system. We have been charged to deliver four new features: introduce a P2P currency as a payment option, update the IINs (or BINs) for a current credit card that we honor, add Spanish as a supported language, and increase the sales tax in the price calculation for intrastate customers. Upon completing these features we will release to our customers (other dev teams) so that they can implement our system into their own. Our current version is v1.4.1 what will be our first release candidate for this release?

Well, this is easy enough. We can just ask a few simple questions and find our answer.

  1. Do these features modify existing public APIs?
  2. Are these features patches for a critically buggy prod version?
  3. Are these features an RND initiative that may or may not ever see production?
  4. Is this one release candidate of a potential set of release candidates?

Let’s take these one at a time:

Do these features modify existing public APIs? If the answer is no, it’s not a major version. If the answer is yes, then it is. Just know that when I say change, I mean actual functional change. If you are correcting a misspelled parameter name, for example, this wouldn’t necessarily constitute a major version increase. The intention here is to indicate that your new version is no longer expressly compatible with the version before it. In our example here, we will certainly be updating our public APIs to support P2P currency, but this will not adversely impact our current dependents so it does not necessarily constitute a major version increase.

Are these features patches for a critically buggy prod version? If the answer is yes, then you are dealing with a branch increment. In this example, we are not.

Are these features an RND initiative that may or may not ever see production? If the answer is yes, then you are dealing with a branch increment. In this example, we are not.

Is this one release candidate of a potential set of release candidates? If the answer is yes, then this is an iteration increment. If this is the first iteration increment either the major and minor, or minor version should be updated as well. In this example, this will be our first release candidate, and, per our previous questions, this will be a minor version increment.

So, all of that said, let’s look at how a portion of this codebase’s life might look with respect to versioning.

  • Since we have a current version v1.4.1 and, due to the answers to our questions, have determined that we are only doing a Minor version increase, when we believe that we are ready to go live and are looking for that final round of testing from our stakeholders, we will tag rc1.5.0.1.
  • Now, let’s say that we still have not gone live, for whatever reason, and have another release candidate, what will be our version? rc1.5.0.2.
  • Now, let’s say that it is determined that it is the first release candidate that will go live. We will tag our rc1.5.0.1 as v1.5.0 and go live with it.
  • But then let’s say that there was a bug in that prod version. We will branch to b1.5.1.1, and begin implementing our fixes.
  • While this is happening we want to spin off an RND initiative. We will branch again to b1.5.2.1.
  • Now, we release our patch so we tag a new prod from our branch v1.5.1.
  • And now, the RND team needs to get these updates so they do and continue their work. It is their responsibility to ensure that their RND is compatible with the latest, and their work should not slow our ability to release to prod.
  • It’s release day again and we go live with v1.6.0.
  • Now, RND has to get the latest and merge in their current branch into their new branch or report their findings. They are the ones who branched, it is their responsibility to ensure that their findings are current, relevant, compatible, and valuable. b1.5.1.1 -> b1.6.1.1.
  • Now, the RND team has found some amazing results, but require an API change for their optimizations to work. This is allowed and they release the updates with the new features in our next release. On to v2.0.0.
  • And so on, and so on…..

And there you have it. Quick, easy, straightforward rules for versioning. I hope that you find this useful, that it frees you from the every arising versioning conversation, and gives you more free time to…… do whatever it is that you do on your free time. Me? I’m going to get back to coding!

I hope that you find this useful, and, if so, put it to good use!

Please, comment on and share this post with others if you enjoy it; follow @kodmunki on Twitter for regular updates on new developments, deployments, articles, and tools; check out kodmunki™ on Github for cool, managed, and tested kodmunki™ projects, and find heavy tunes to flip bits to on komdunki™ SoundCloud page.
Thank you for reading, and as always, happy coding :{)}




Architect, engineer, and deliver, intentional, quality, valuable software. Interested in working together? Let's chat.

Posted in Best Practices, Development, Workflow
One comment on “Versioning
  1. […] Versioning: a post that aims to put a stop to the needless recurring questions about versioning your software. […]

Enjoy the read? -- Let us know.

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

kodmunki™ Tweets

Enter your email address and receive notifications of new kodmunki™ posts by email.

%d bloggers like this: