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
RevisionThis is the number taken from source control to identify what
was actually built.BuildThis 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.MinorThis 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.Majorindicates 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
AssemblyVersionandAssemblyFileVersionattributes 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
AssemblyVersionandAssemblyFileVersionattributes 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.