Ruthlessly Helpful

Stephen Ritchie's offerings of ruthlessly helpful software engineering practices.

Build Numbering and Versioning

Build numbering is a topic filled with “political” and “cultural” significance. I mean that within organizations and among developers, we have heated debates over the numbering of software versions. Is this software 2.3 or 3.0? Or should it be, 2.3.5.rc-1, or 2.3.5.beta?

Phil Haack recently offered some important information on Semantic Versioning (SemVer) specification and NuGet build numbering. Since the SemVer convention is a rational and meaningful way to version public APIs, it’s a good one to follow. Here are Phil’s posts:

The basics of SemVer: the version number has three parts, Major.Minor.Patch, which correspond to:
Major: Backwards incompatible changes
Minor: New features that are backwards compatible
Patch: Backwards compatible bug fixes only.

Everything after these three numbers is for a development organization to use, as it sees fit. Personally, I like ever-increasing, always-unique-for-a-major.minor-version integer numbers. Whether these are build numbers or revision numbers they can be managed by the build script or the continuous integration server.

However, build numbering and versioning has political and cultural significance and implications. Sadly, developers cannot always follow rational and meaningful numbering schemes.


The Marketing Department of a commercial software company often wants to control the first two digits of the build number. They love to promote things like the company’s software is no longer version 2.3; now it’s 3.0! This change in major version generates interest and drives upgrade sales. In some cases, the software is a major new release, with significant new features. In other cases, it is just a marketing gimmick; there are only bug fixes and cosmetic changes in the new version.

Internally, developers hate it when Marketing overstates the major and minor version numbers of software. They feel that a minor release does not warrant an increment of the major version number. They want to follow systems like SemVer.

My opinion: As long as the numbers don’t violate the conventions of SemVer, let the major and minor version numbers belong to Marketing.

Marketing controls the product name. I have seen some crazy product name changes come from Sales and Marketing. As long as it isn’t too absurd, I go along with it. Why shouldn’t that be the same way with the major and minor version numbers? If Marketing wants 2.2 to be followed by 3.0, that’s OK with me. Going from 2.2 to 2.5 could represent a more accurate description of the perceived improvement. Either way, I don’t see it as my call. What I don’t like is jumping from 2.2 to 5.0 or regressing from 2.2 to 1.7, that’s absurd. The major version number should never increment by more than one. The combined major and minor number should always represent a decimal number greater than the prior version. Similarly, going from 2.2 to 2.3 must only introduce backwards compatible new features and backwards compatible bug fixes.

Bottom line, let Marketing own the major and minor version numbers. Insist that they follow the basic rules. Give them the guidance that increasing the major version number means “breaking changes are introduced”, “significant new features are added” or “it’s a total rewrite.” Minor version numbers are incremented when minor enhancements are added and bug fixes are made. Marketing must not break the paradigm. They are adults. If they are using sound judgement, let them own the major and minor numbers.

NuGet and the Nu World Order

In the .NET world, NuGet is very significant. With version 1.6, NuGet follows the SemVer specification. My current thinking on version numbering is that you ought to follow the version numbering that NuGet follows. The NuGet documentation describes the SemVer spec and what NuGet expects of version numbering.

Continuous Integration Server

The CI server is a great way to control and increment the version number.

Cruise Control .NET (CCNet) has the Assembly Version Labeller and TeamCity has the AssemblyInfo Patcher.

Incorporate this version numbering into your build script. Chapter 9 of Pro .NET Best Practices covers this topic. The free code samples are available at the bottom of the Apress page for the book, here.

Here is a good way to version assemblies:

Ben Hall describes how to increment the build numbers with MSBuild and TeamCity:

Wikipedia, as usual, has a comprehensive entry on the topic of software versioning:


One response to “Build Numbering and Versioning

  1. Pingback: Versioning git projects | T+Code

Leave a Reply

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

You are commenting using your 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

%d bloggers like this: