In this post, I will introduce you to semantic versioning and explain why you should be using it as a standard for versioning your products. I will then walk you through how to add support for semantic versioning to your .NET projects.
Product versioning has always been a tricky paradigm. There used to be no rules and everyone had their opinion what versions should be like. Initially, versions were probably just Version 1, Version 2, etc. Then someone probably decided that a bug fix probably did not justify going from Version 1 to Version 2, so they added another number to indicate that the release was a bug fix, so we ended up with Version 1.0 with Version 1.1 being a bug fix release. Next someone decided that having the bug fix number as the second number was not a good idea because he wanted to indicate that a release received new incremental functionality that did not break existing functionality, but also still be able to do bug fix releases, so we ended up with versions like 1.0.0, 1.1.0, and 1.1.1. Along the way, product marketing groups joined the version conundrum and everyone started using the year in which the products were published, so we ended up with products like Windows 95 and Office 2010.
For software developers, versioning has always been a source of constant frustration. Before .NET, Windows developers constantly faught a conundrum that was dubbed DLL Hell. DLL Hell happens when a dynamic link library being used by an application is updated with potentially breaking changes. This becomes especially problematic if multiple programs share the same DLL. This could happen, for example, because Windows uses the PATH environment variable to resolve references to dynamic link libraries used by EXE or other DLL modules. DLLs did not natively have any concept of a version number, and native code linked only to the DLL module, and not to a specific version of the DLL.
The introduction of the .NET Framework attempted to solve this issue and eliminate Dll Hell developers by introducing a version number into .NET assemblies and linking .NET programs and libraries against specific versions of other assemblies. To support this versioning concept, .NET introduced a version number with 4 parts. The first two numbers are the major and minor version. The major version is typically used to indicate the major release and the minor version can be upgraded if there are enhancements to the product that do not warrant a major release. But those last two components are somewhat ambiguous. There is no specific standard defined for people to follow, and if you used the standard .NET templates that came with Visual Studio, the .NET compiler would auto-generate the last two parts of the version number.
Along the way, something happened that typically happens with problems such as versioning: someone became frustrated. Actually, many people became frustrated, but we all waited for someone to get frustrated enough to present a clever solution that made sense. And out of that frustration, the Semantic Versioning standard was born.
Semantic versioning is a community standard that brings standard meaning to product versioning. The goal is that the version number of a product communicates what changes occurred between two versions of a product, or communicates additional information to let users know about whether a product is ready for them to use.
A semantic version number has five components:
- The major version number
- The minor version number
- The patch version number
- An optional pre-release version identifier
- An optional build number
The major version number is a non-negative number that indicates the major release of the software product or library. Every product release that shares the same version number should be backwards compatible with earlier releases and should not introduce any breaking behavior or functionality.
The minor version number is used to indicate whether new functionality has been introduced between releases. For example, if I release a product with a version number of 1.0 and two months later release version 1.1, this indicates that version 1.1 is backwards compatible with version 1.0, but there have been additional features added to the product.
The patch version number is used to indicate that bugs have been fixed between releases, but the software is basically the same. This means that if I have a product with a version 1.2.0 and I release 1.2.1, the software is functionally equivalent to version 1.2.0, but contains bug fixes that corrects problems found in version 1.2.0. No new functionality is allowed when releasing patches.
When developing software, it is typical that I will generate what is known as a pre-release build. A pre-release build is typically provided to QA, project stakeholders, and select customers or early adopters in order to collect feedback on new features. Pre-release builds are typically labelled using Greek letters. For example, an alpha release is usually a snapshot of the software product while in development. An alpha release will be buggy and untested, and it is not feature complete. Once the product has initial implementations of all of the features to be included in the next release, another pre-release called a beta release will happen. Beta releases are typically provided to a larger group of early adopters, either internal or external, and are usually feature complete but are untested and contain bugs. Beta releases are intended to get significant end-user testing in real world scenarios before going out to all customers in an official release. Finally, after millions of hours going through bug reports, the product will approach a level of stability and the product team will produce what is called a release candidate. The release candidate build is passed around some final testers, shown to customers by the sales teams, and eventually one of these candidates will eventually be promoted to the official release.
The important meaning behind the pre-release version is that it is used to indicate to consumers that the product is a pre-release and not a formal release. Using the pre-release version component, a consumer can see what state the product is in. For example, if the user is not adventurous, he can skip alpha releases and wait for the release candidate. The pre-release version number can also be a string and contain multiple parts. For example, I may use a pre-release version of beta.3. This indicates that the release is the third beta release, so if a user is using the second release, they will know that this release is an update that may contain some bug fixes that they have been waiting for.
The final component is the build version. The build version is more of a development tag and can be used by the development team to match a specific build to a commit or change set in the version control repository, or to a specific build identifier from a build server. For example, if you are using Git for your version control system, the build number may be the SHA-1 hash or prefix of the commit that the build is based on. If you are using Microsoft’s Team Foundation Server, the build version may contain the integer identifier of the change set that the build is based on. I use JetBrains TeamCity to build my software and TeamCity maintains an incrementing identifier for each build. I include this in my build version number for my products.
Semantic version numbers have the following format:
The pre-release and build versions are optional, but the major, minor, and patch versions are required. Here are some examples of valid semantic versions:
Besides the format of the version number, there are rules, some of which I have already covered. For example, if you fix a bug and release it to customers, you need to increment the patch version. If you add new functionality but do not break backwards compatibility with previous versions, you have to increment the minor version. Further, if you increment the minor version, you have to reset the patch version to zero. If you break backwards compatibility with earlier versions, you need to increment the major version and reset the minor version and patch version to zero.
Remember that major, minor, and patch versions are non-negative numbers. That means that they can be zero. When you are developing the initial version of your product and have not released it for production use, you are allowed to use zero for the major and minor versions. But as soon as your product is released for production use by consumers, you must promote the product to version 1.0.0. As long as your version number is in the zeros, you can make any kind of breaking change. But once you reach version 1.0.0, the product needs to be stable and any public APIs that you expose cannot change.
Supporting Semantic Version Numbers in .NET
In order to support semantic versioning in .NET, I am going to show the creation of two classes. The first class, SemanticVersion, actually stores, parses, and represents a semantic version number. The second class, SemanticVersionAttribute, is a custom .NET attribute class that you can use to include the semantic version number in the assembly metadata. By including the version number in the metadata for your assembly, you can programmatically retrieve that version number just like you can the assembly version number or the file version numbers that use the standard .NET four-component version numbering scheme. In the end, I will also show you the code for a custom MSBuild task that you can include in an MSBuild script (or .csproj file, for example) in order to generate a file containing the correct version numbers at build time.
I will start by creating each unit test for the code and then explaining the relevant implementation of that test. At the end of this post, I will post the full source code to the SemanticVersion class, so feel free to skip ahead if you are not specifically interested in how the code works or you want to see it for yourself.
The first step that we need to do is to make sure that the constructor can parse a semantic version number. I will actually define two constructors. The first constructor will take a string containing the semantic version number and will parse it. The second constructor will take the major, minor, and patch version components as integers:
I decorated the SemanticVersion class with the SerializableAttribute attribute so that the version number cam be serialized. This will be important later when we add the version to the assembly metadata. I also marked the class as sealed. This is done to give the class value semantics by making the semantic version immutable. I did this because in the full class definition I implement the Object.Equals and Object.GetHashCode methods and I need to ensure that the state of the object never changes.
My first two tests will test the parsing capabilities of the first constructor:
For unit testing on the Microsoft .NET platform, I prefer to use xUnit.NET. if you are not familiar with it, you can find information about it from its CodePlex repository here. xUnit.NET can be added to your project using NuGet.
The implementation of the constructor is shown below:
In the code segment above, I threw in the second constructor that accepts the major, minor, and patch version numbers as integers, but we’ll focus on the first constructor that parses the semantic version number as a string. To do the parsing of the semantic version number, I am using a regular expression. The regular expression will look for the major version, minor version, and patch version to be strings of one or more digits separated by decimal points. Next, the regular expression will look for an optional pre-release version number that is appended to the version number and preceded by a hyphen. Last, the regular expression will look for an optional build version number that is appended to the version number and preceded by a plus sign. If the regular expression does not match the version number, then an exception is thrown reporting that the version number is not a valid semantic version number.
The above code segment is using Microsoft's Code Contracts to enforce pre-conditions and post-conditions.
The next big implementation piece is to implement the comparison rules according to the semantic version number standard. To compare two semantic version numbers, we have to do the comparison piece by piece. The major, minor, and patch version numbers are compared as integers. If the major version number of the first version is greater then the major version number of the second number, then obviously the first version is greater than the second version. For the pre-release and build versions, we have to further break down these versions into components that are separated by dots (for example, the build version build.12.e8f9256c has three components: build, 12, and e8f9256c). If two components are numeric, then they are converted to integers and a straight integer comparison occurs. If the components are strings, then the strings are compared lexically as ASCII strings. Here are the tests that we will use to validate the implementation of the comparison logic:
Phew! That’s a lot of tests. I used JetBrains dotCover to do the code coverage while I wrote the tests, so they should hopefully be pretty complete. Now that the tests are done, here’s the code to implement all of these comparisons:
If you look at the above code sample and notice that the CompareBuildVersions and ComparePrereleaseVersions methods are identical, you’re almost right. At the beginning, the return values are opposite of each other depending on whether the build/pre-release versions are present in the semantic version or not. I can probably refactor this to share the rest of the code, but it’s ok for the moment. With this logic added to the class, all of the comparison rules for semantic versions should be equal now and we should be able to compare SemanticVersion objects.
Labeling Assemblies with Semantic Versions
Now that we have the SemanticVersion object, we can attach the semantic version to the metadata for our assemblies. To do this, I created a new attribute class called SemanticVersionAttribute:
This attribute can be attached to your AssemblyInfo.cs file by adding the following statement:
However, while that works, you probably do not want to do that. A better solution for managing the version numbers in your assemblies is to create a custom MSBuild task that will output another file that contains the version numbers to use for the assembly for the specific build that is being built. I use a custom MSBuild task that I created that will generate a file named VersionInfo.cs that contains the following attributes:
This task can be implemented inline in your MSBuild script using the new factory feature of MSBuild 4.0:
In my build environment, the version numbers are calculated from information provided by my build server (TeamCity). Using this task, I can then create the VersionInfo.cs file and replace the one that I use to compile with inside of Visual Studio when I am developing. In my MSBuild script, I can use this task like so:
In this post, I had hoped to introduce you to semantic versioning, explain some of the benefits of semantic versioning as a standard for versioning your own products, and then show you how you can make use of semantic version numbers in your .NET programs. I have created a Gist on GitHub containing the full, commented source code that I showed off in this post. You can find it at https://gist.github.com/4624831.