Best practices for assembly naming and versioning?

Question

I am looking out for some good practices on naming assemblies and versioning them. How often do you increment the major or minor versions?

In some cases, I have seen releases going straight from version 1.0 to 3.0. In other cases, it seems to be stuck at version 1.0.2.xxxx.

This will be for a shared assembly used in multiple projects across the company. Looking forward to some good inputs.

Answer 1

Some good information from this article on Suzanne Cook's blog on MSDN (posted 2003-05-30):

When to Change File/Assembly Versions

First of all, file versions and assembly versions need not coincide with each other. I recommend that file versions change with each build. But, don’t change assembly versions with each build just so that you can tell the difference between two versions of the same file; use the file version for that. Deciding when to change assembly versions takes some discussion of the types of builds to consider: shipping and non-shipping.

Non-Shipping Builds
In general, I recommend keeping non-shipping assembly versions the same between shipping builds. This avoids strongly-named assembly loading problems due to version mismatches. Some people prefer using publisher policy to redirect new assembly versions for each build. I recommend against that for non-shipping builds, however: it doesn’t avoid all of the loading problems. For example, if a partner x-copies your app, they may not know to install publisher policy. Then, your app will be broken for them, even though it works just fine on your machine.

But, if there are cases where different applications on the same machine need to bind to different versions of your assembly, I recommend giving those builds different assembly versions so that the correct one for each app can be used without having to use LoadFrom/etc.

Shipping Builds
As for whether it’s a good idea to change that version for shipping builds, it depends on how you want the binding to work for end-users. Do you want these builds to be side-by-side or in-place? Are there many changes between the two builds? Are they going to break some customers? Do you care that it breaks them (or do you want to force users to use your important updates)? If yes, you should consider incrementing the assembly version. But, then again, consider that doing that too many times can litter the user’s disk with outdated assemblies.

When You Change Your Assembly Versions
To change hardcoded versions to the new one, I recommend setting a variable to the version in a header file and replacing the hardcoding in sources with the variable. Then, run a pre-processor during the build to put in the correct version. I recommend changing versions right after shipping, not right before, so that there's more time to catch bugs due to the change.

Answer 2

One way to define your versioning is to give semantic meaning to each portion:

• Go from N.x to N+1.0 when compatibility breaks with the new relase
• Go from N.M to N.M+1 when new features are added which do not break compatibility
• Go from N.M.X to N.M.X+1 when bug fixes are added

The above is just an example -- you'd want to define the rules that make sense for you. But it is very nice for users to quickly tell if incompatibilities are expected just by looking at the version.

Oh, and don't forget to publish the rules you come up with so people know what to expect.