Having a good version scheme for your software is important for several reasons. The following are the top five things a version scheme allows you to do (in random order):

So, how do you keep track of files in a product and link them back to the owner? How can you tell that you are testing or using the latest version of a released file? What about the rest of the reasons in the list? This chapter describes my recommendations for the most effective and easiest way to set up and apply versioning to your software. Many different schemes are available, and you should feel free to create your own versioning method.

Ultimately, like most of the other topics in this book, the responsibility to apply versioning to the files in a build tends to fall into the hands of the build team. That might be because it is usually the build team that has to deal with the headaches that come from having a poor versioning scheme. Therefore, it is in their best interest to publish, promote, and enforce a good versioning scheme. If the build team does not own this, then someone who does not understand the full implications of versioning will make the rules. Needless to say, this would not be desirable for anybody involved with the product.

What is the best way to accomplish this? Let’s start with the version number and work our way down.

Every file in a product should have a version number; a four-part number separated by periods such as the one that follows seems to be the established best practice. There are many variations of what each part represents. I will explain what I think is the best way of defining these parts.

<major version>.<minor version>.<build number>.<revision>

As a rule of thumb, each codeline in a source tree should have its own build number, and that number should start at zero when the branch is created. If it is a build off of the main trunk, the build number should go into the <revision> field. Keep your mainline incrementing with each build as long as it is still the tip of your source tree. See Chapter 16, “Managing Hotfixes and Service Packs,” for detailed examples on this labeling.

For example, 5.1.2600.2180 is a typical file version for a Windows XP SP2 binary. Let’s break this down in more detail:

How can this revision build number (2180) be smaller than the original XP RTM build (2600)? The reason is because the SP2 codeline is a branch off the XP mainline (the 2600 codeline). When the branch was made, the build number was reset to 0. The large number of builds is a result of SP2 containing all the SP1 changes, which was the same branch. (The RTM build number was 1086 for SP1.) If this was a one-off hotfix rather than a service pack release, the <revision> field might have the number of the bug that was being fixed, such as 1000 (if this was the bug number). Again, to better visualize this, see the sample VSS tree drawings in Chapter 16.

Each build that is released out of the Central Build Lab should have a unique version stamp (also known as the build number). This number should be incremented just before a build is started. Don’t use a date for a build number or mix dates into a version number simply because there are so many date formats out there that it can be difficult to standardize on one. Also, if you have more than one build on a given date, the naming can get tricky. Stick with an n=n+1 build number. For example, if you release build 100 in the morning and rebuild and release your code in the afternoon, the afternoon build should be build 101. If you were to use a date for the build number, say 010105, what would your afternoon build number be? 010105.1? This can get rather confusing.

It is also a good idea to touch all the files just prior to releasing the build so that you get a current date/time stamp on the files. By “touching” the files, I simply mean using a tool (touch.exe) to modify the date/time stamp on a file. There are several free tools available for you to download, or you can write one yourself. Touching the files helps in the tracking process of the files and keeps all of the dates and times consistent in a build release. It also eliminates the need to include the current date in a build number. You already have the date by just looking at the file properties.

In addition, try to avoid tools that inject version numbers into binaries (as a post-build step). Although the tools might seem reliable, they introduce an instability factor into your released binaries by hacking hexadecimal code. Most Q/A teams become distressed if this happens to the binaries they are testing—and justifiably so. The build number should be built into the binary or document files.

This would be a good time to review Chapter 2, “Source Tree Configuration for Multiple Sites and Parallel (Multi-Version) Development Work,” or jump ahead to Chapter 16 unless you are able to follow this without the visuals.

All the source code control (SCC) software that I have seen has some kind of labeling function to track either checked-in binaries or source code. (Remember that I am not for checking in binaries, but I mention this for the groups or teams that do. See Chapter 2.) This type of versioning (or more appropriately named labeling) is typically used to track a group of sources that correspond to a product release. Most of the time, they combine labeling of the sources with the branching of the source code lines.

I like to stick to the recommended practice of branching as infrequently as possible. Some companies and groups at Microsoft branch code off the main source line after every build and use the build number as the label. Their source tree usually ends up being an administration nightmare because some critical files get buried so deep that they forget they are there, and their SCC tool does not have a good way of managing them and bringing them back to the surface or top level of the tree.

Regardless of the SCC tool you use, keep your labeling simple, and use the build number that the sources or files were built with. As mentioned in Chapter 2, if you would like a deeper look at SCC tools, I highly recommend Software Configuration Management Patterns by Berczuk and Appleton. The detail on source control that is covered in that book is unmatched.

I am of the opinion that no, there shouldn’t be other fields in the file version number. Let’s look at some other fields that might seem like they should be included but really don’t need to be:

There might be one exception to adding a fifth field that falls under the external releases of your product: You might want to add the word .BETA at the end version string so that people will know at a quick glance that they are running beta code upon checking the version. Some testers argue that this extra field, which would be truncated on the final release, changes the byte count of the binaries, which then would affect the testing. This is probably true, so you have to weigh the consequences.

This section applies to you only if you are programming in .NET.

When Microsoft introduced .NET, one of its goals was to get rid of DLL hell and all the extra setup steps I talk about later in this chapter. In reviewing where .NET is today, it looks like Microsoft has resolved the sideby-side DLL hell problem, but now the problem is “assembly version hell.” Without going into too much detail about the .NET infrastructure, let’s touch on the difference between file versioning and assembly versioning.

Assembly versions are meant for binding purposes only; they are not meant for keeping track of different daily versions. Use the file version for that instead. It is recommended that you keep the assembly version the same from build to build and change it only after each external release. For more details on how .NET works with these versions, refer to Jeffrey Richter’s .NET book. Don’t link the two versions, but make sure each assembly has both an assembly version and a file version when you right-click. You can use the same format described earlier for file versioning for the assembly version.

Have you ever met someone who reformats his machine every six months because “it just crashes less if I do” or it “performs better?” It might sound draconian, but the current state of component versioning and setup makes starting from scratch a likely solution to these performance issues, which are further complicated by spyware.

Most of the problems occur when various pieces of software end up installing components (DLLs and COM components) that are not quite compatible with each other or with the full set of installed products. Just one incorrect or incorrectly installed DLL can make a program flaky or prevent it from starting up. In fact, DLL and component installation is so important that it is a major part of the Windows logo requirement.

If you are involved in your product’s setup, or if you are involved in making decisions about how to update your components (produce new versions), you can do some specific things to minimize DLL hell and get the correct version of your file on the machine.

Installing components correctly is a little tricky, but with these tips, you can install your components in a way that minimizes the chance of breaking other products on your own.

Even if you follow all the preceding steps and install everything 100 percent correctly, you can still have problems caused by updating components. Why? Well, even though the new component is installed correctly, its behavior might be different enough from the old component that it breaks existing programs. Here is an example. The specification for a function says that a particular parameter must not be NULL, but the old version of the component ran fine if you passed NULL. If you enforce the spec in a new version (you might need to do this to make the component more robust), any code that passes NULL fails. Because not all programmers read the API documentation each time they write a call, this is a likely scenario.

It is also possible for a new version to introduce a bug that you simply didn’t catch in regression testing. It is even possible for clients to break as a result of purely internal improvements if they were relying on the old behavior. Typically, we assume that nothing will break when we update a component. In fact, according to Craig Wittenberg, one of the developers of COM who now works in the ComApps group at Microsoft, if you don’t have a plan for versioning your components in future releases, it is a major red flag for any component development project. In other words, before you ship Version 1, you need to have a plan for how you will update Version 1.1, Version 2, and beyond—besides how to bug-fix your updates.

In the past, it has been common to share components by default and update them whenever needed. This approach has caused many problems with system stability, although it has been efficient in terms of memory and disk usage. Clearly, a less chaotic set of guidelines is needed. With disk and memory so inexpensive today, a growing number of people argue that applications should never share non-system component files, that the stability costs of sharing far outweigh the storage and performance benefits of sharing. This does not mean that you shouldn’t use components; it just means that you should allow each application to use the version of the component it was tested with. By not sharing the component files while using components, you get almost all the benefits of component development without destabilizing your users’ systems.

Sometimes it is appropriate to share component files, such as the Office DLL (MSOFFICE.DLL). If you do decide to share component files among applications, make sure all the users of the shared component files understand the versioning plan. And never write such components to system directories.

In this chapter, I covered why versioning is important and how it applies to build, source tree labels, .NET assemblies, and setup. The main point in this chapter is to make sure you have a good versioning scheme and to keep it consistent throughout your product. The four-part number scheme discussed in this chapter has been effective for the product groups at Microsoft for years.

What I recommend is to read and re-read this chapter to make sure you fully understand everything in it and to grasp the importance of reliable versioning. Here is a short list of what you need to do: