Version Numbers, Roadmaps, and Code Names

Version Numbers

Version numbers should provide information. This is something I like about semantic versioning ( which allows you to imply compatibilty via the version number.

Semantic Versioning[1] is a formal convention for specifying compatibility using a three-part version number: major version; minor version; and patch. The patch number is incremented for minor changes and bug fixes which do not change the software’s application programming interface (API). The minor version is incremented for releases which add new, but backward-compatible, API features, and the major version is incremented for API changes which are not backward-compatible. For example, software which relies on version 2.1.5 of an API is compatible with version 2.2.3, but not necessarily with 3.2.4.

In a system where bug fixes and features are being added frequently this helps users who are trying to determine the possible benefit as well as the potential effort involved in upgrading.


One of the big issues with using semver in a frequent-release project is that you can end up conflicting with version numbers laid out in product roadmaps. Product groups will need to build roadmaps indicating when features or fixes will be released and when they do this the initial urge will be to pin a version number to it.

  • “KittyLib 3.1.4 will contain bugfix X and be released on 2016/01/13”
  • “Feature Y will be released in KittyLib 3.2.0 early Q2”

This feels natural and seems reasonable but can cause problems when something comes up suddenly and forces a new bug-fix or feature release.

If a roadmap has been presented to users/stakeholders that says KittyLib 3.2.0 will be out early Q2 and contain features Y and Z then inevitably, at some point before that date, a new API addition is going to be required. Maybe that isn’t feature Y or Z (or maybe feature Y is ready early, why hold back a good thing?) and now you’ve got to decide between shoving an API addition into a patch version (violating the semver numbering rules and making you itch uncontrollably) or updating the roadmap which may or may not be time consuming and confusing to stakeholders.

If your team has regularly gone 6+ months without anything unexpected needing to be released then kudos, but I have a feeling that’s a rare thing.

But what can we do? We need roadmaps to keep stakeholders happy (among other reasons) and we really want informative version numbers.

Code Names

Both fun and useful: code names are a handy solution when you want to remove your now meaningful version numbers from roadmaps.

  • “Bugfix X is expected to be in KittyLib ‘Moonraker’ with a pending release date of 2016/01/13”
  • “Feature Y will be released in KittyLib ‘Goldfinger’ early Q2”

When the release containing bugfix X is ready then you are able to either replace the code name with the version or simply associate it with the version:

  • “KittyLib 3.3.4 ‘Moonraker’ has been released, it includes bugfix X”
  • “KittyLib 3.4.0 has been released, it includes features Y and Z”
The point is to set a Major.minor.patch version when you do the release, not before. That way you know what the numbers actually need to be.

Another alternative is to just give projected release dates for bugs/features without providing a version or code name. This is the option least likely to come back to bite you in terms of development and unexpected releases; however I find codenames make it easier to reference.

  • “Bugfix X is expected to be released the week of 2016/01/13”
  • “Feature Y will be released early Q2”

There are lots of options around presenting your roadmap and referring to releases. The most important thing is to try and understand how you are restricting yourself and what the needs of your particular project and users will be.