Best practices/guidance for maintaining assembly version numbers

Question

I'm looking for pointers, suggestions, and even dictation on how to manage the three different assembly version numbers for a .NET assembly. The Product version is the simplest, as this seems would normally be dictated by business. Then, the file version seems to be for versioning between deployments, where the actual assembly version is only used when shipping.

Right now I'm just looking for a simple means of labeling test and maintenance releases of an assembly on which none depend, so I am looking at auto-incrementing build and revision numbers on the file version, and for final release, copying the current file version to the assembly version. The product is in production use, but still under development - you know - one of those small company, no change control infrastructure situations.

Answer 1

Versioning is something that I am very passionate about and have spent a long time trying to come up with an easy to use versioning system. From what you have already said in your question it is clear that you have understood one important point, the assembly version numbers are not synonymous with the product version. One is technically driven, and the other is driven by the business.

The following assumes that you use some form of source control and a build server. For context we use TeamCity and Subversion/Git. TeamCity is free for a small (10) number of projects and is a very good build server but there are others, some of which are completely free.

What a version number means

What a version means to one person may mean something different to another, the general structure is major, minor, macro, micro. The way I look at a version number is to break it down into two parts. The first half describes the main version (Major) and any key updates (Minor). The second half indicates when it was built and what the source code version was. Version numbers also mean different things depending on the context, is it an API, Web App, etc.

Major.Minor.Build.Revision

• Revision This is the number taken from source control to identify what was actually built.
• Build This is an ever increasing number that can be used to find a particular build on the build server. It is an important number because the build server may have built the same source twice with a different set of parameters. Using the build number in conjunction with the source number allows you to identify what was built and how.
• Minor This should only change when there is a significant change to the public interface. For instance, if it is an API, would consuming code still be able to compile? This number should be reset to zero when the Major number changes.
• Major indicates what version of the product you are on. For example the Major of all the VisualStudio 2008 assemblies is 9 and VisualStudio 2010 is 10.

The exception to the rule

There are always exceptions to the rule and you will have to adapt as you come across them. My original approach was based on using subversion but recently I have moved to Git. Source control like subversion and source safe that use a central repository have a number that can be used to identify a particular set of sources from a given time. This is not the case for a distributed source control such as Git. Because Git uses distributed repositories that are on each development machine there is no auto incrementing number that you can use, there is a hack which uses the number of check-ins but it is ugly. Because of this I have had to evolve my approach.

Major.Minor.Macro.Build

The revision number has now gone, build has shifted to where the revision used to be and Macro has been inserted. You can use the macro how you see fit but most of the time I leave it alone. Because we use TeamCity the information lost from the revision number can be found in the build, it does mean there is a two step process but we have not lost anything and is an acceptable compromise.

What to set

The first thing to understand is that the Assembly Version, File Version and Product Version do not have to match. I am not advocating having different sets of numbers but it makes life a lot easier when making small changes to an assembly that doesn't affect any public interfaces that you are not forced to recompile dependent assemblies. The way I deal with this is to only set the Major and Minor numbers in the Assembly Version but to set all the values in the File Version. For example:

• 1.2.0.0 (AssemblyVersion)
• 1.2.3.4 (FileVersion)

This gives you the ability to roll out hot fixes which will not break existing code because the assembly versions do not match but allow you to see the revision/build of an assembly by looking at its file version number. This is a common approach and can be seen on some open source assemblies when you look at the assembly details.

You as the Team lead would need to be responsible for incrementing the minor number when ever a breaking change is required. One solution to rolling out a required change to an interface but not breaking previous code is to mark the current one as obsolete and creating a new interface. It means that existing code is warned that the method is obsolete and could be removed at any time but doesn't require you to break everything immediately. You can then remove the obsolete method when everything has been migrated.

How to wire it together

You could do all the above manually but it would be very time consuming, the following is how we automate the process. Each step is runnable.

• Remove the AssemblyVersion and AssemblyFileVersion attributes from all the project AssemblyInfo.cs files.
• Create a common assembly info file (call it VersionInfo.cs) and add it as a linked item to all your projects.
• Add AssemblyVersion and AssemblyFileVersion attributes to the version with values of "0.0.0.0".
• Create an MsBuild project that builds your solution file.
• Add in a task prior to the build that updates the VersionInfo.cs. There are a number of open source MsBuild libraries that include an AssemblyInfo task which can set the version number. Just set it to an arbitrary number and test.
• Add a property group containing a property for each of the segments of the build number. This is where you set the major and minor. The build and revision number should be passed in as arguments.

With subversion:

<PropertyGroup>
    <Version-Major>0</Version-Major>
    <Version-Minor>0</Version-Minor>
    <Version-Build Condition=" '$(build_number)' == '' ">0</Version-Build>
    <Version-Build Condition=" '$(build_number)' != '' ">$(build_number)</Version-Build>
    <Version-Revision Condition=" '$(revision_number)' == '' ">0</Version-Revision>
    <Version-Revision Condition=" '$(revision_number)' != '' ">$(revision_number)</Version-Revision>
</PropertyGroup>

Hopefully I have been clear but there is a lot involved. Please ask any questions. I will use any feedback to put a more concise blog post together.

• Version numbers in a compiled assembly
• MSBuild Extension Pack
• TeamCity