A Simple Version Control Strategy Using Team System

• Parts of this article are compiled from http://msdn.microsoft.com/library/en-us/dnvs05/html/vs05teamsys.asp?frame=true

Update: Added questions about sstoring third party components, sharing project output internally and branching compared to Subversion.

I was recently asked by a client who I'm helping to integrate Team System, to create a strategy for the organization and future projects for managing multiple versions of applications and code - A version Control Strategy.

Since there are some major difference between the way Team System Works and its current abilities compared to past versions of Microsoft Source Control Products like VSS (or other 3^rd party products such as CVS), I turned to look for a good source of information on this. The more I searched I less I found that made sense. There are tons of scattered material out there on the technical aspects of version control (very little on Team System but there is some) but almost none about the strategy you might want to use when dealing with multiple versions.

I asked several of my colleagues, all working with Team System, to tell me what strategy they use for versioning control of applications. They all said that they are also “re-inventing the wheel” – They couldn’t find any clear guidance either on this.

So I decided to put my thoughts on paper and publish it, so that :

• I can get feedback
• You won’t have to reinvent the wheel yourself.

It’s important to understand that besides the simple “What do I do when I have a new version”, the technicalities of what you do in team system were compiled from other sources, mainly the one listed at the top of this page.

This short guide is nothing more than that –a short guide, that tells you the basic strategy you need to follow. That mindset is what’s important. It’s not a 90 page document. It’s a strategy document, and as that is should be simple.

Over time I will sprinkle various “HOWTO” links around the article to point to various “gotchas” when trying to accomplish some of the stuff mentioned here. A good example might be coming up with the appropriate versioning scheme that automatically changes the last build number based on your input. It’s a relatively simple task, but with the current crop of Team System Tooling (namely- none),  it’s pretty hard to achive without lots of manual labour. I will add that link later on when I’ve written a short essay on those little pitfalls we like to call “Extending Team Build”.

The article is in the form of Questions (FAQ) that you ask yourself during development. The first two are just background and opening though. Hope the format is useful.

Roy.

Team Foundation Source Control Vs SourceSafe

Make no mistake about it:

TFVC was written from the ground up to solve limitations of using VSS on large development projects. Instead of relying on a file system as the repository, TFVC leverages Microsoft SQL Server 2005 as a robust, scalable, high-performance storage mechanism.

Team Foundation Version Control provides all of the basic functionality of other source control mechanisms and most of the enhancements listed for Visual SourceSafe 2005. In addition, TFVC provides new advanced feature, including Shelving, checkin policies, and integration with the new work item tracking system. These features are described later in this article.

There are a few features that VSS users may miss from TFVC. These features include:

• Sharing—VSS provides a mechanism to make a file or folder in source control appear in multiple places in the source control structure. TFVC does not have an identical capability. Branching, however, can be used to simulate this behavior.
• Pinning—VSS provides a mechanism called "Pinning," which is used to pin a version of a file in such a way that it can't be modified. This is frequently used with sharing, to pin different versions of the same file in different share directories. As described below, the TFVC mechanisms for branching are more powerful, in that they allow different versions to be maintained independently.

What's the basic strategy for handling multiple versions of my application?

The guiding rule of thumb for me is::

• Use labels for bug fixes in the current version (version increments should be 1.0.X.0)
• Use Branches for New features (version increments should be X.0.0 or  1.X.0.0)
• Use the remaining fourth number (1.0.0.X) at your discretion for maintaining unique build numbers across revisions.
• (The MS guideline states that the order of these should be MajorVersion.MinorVersion.Build.Revision - This is different than what this article states. I find my way clearer to understand)

Versions which are just bug fixing versions (no new features) are better solved using Labeling in the current product root in Team System Source Control. For versions with new features, Branching is the standard answer. When you release a version of your application, you create a branch of your files for the next version. Just like the branches in a tree, you can access all existing branches simultaneously. Now, when your high priority bug comes in on V1.0 of your application, you can go back to that branch and make the fixes, without worrying about the impact your V2.0 updates could cause.

But Now that you've prepared a new V1.1 release with the bugs fixed, how do you make sure that those updates are reflected in the V2.0 code that you're working on? The preferred solutions the use of the  merge tool from Team System.

What should I do when I have released a version to my users?

• Create a label on the top branch of that product you just released with the label (Release Version X.y.z).
  • This will allow you to fix bugs in the just released version without affecting future versions.
• Create a new branch from that release version (from the root of the product) into a new tree node usually named "myProduct-v11" or "MyProduct-v20".
  • This will allow you to add features without disturbing the stability of the old version.

I want to start creating the next version of my product

• If your new version will contain new features, use the new branch you created after the previous release to all the development in.
• If your new version is simply a bug fixing version, nothing else, you may be better off labeling the just released version for each bug fix

Where should I store any third party components and libraries that my project uses?

• I believe that each version of the project needs all of the binaries it's worked with, with their own version, so that when you need to, you can recreate any bug with any version of any 3rd party component. Those components are then branched as well with each new version of the software.

We're writing a project that's used inside the organization. How do we make sure people always get the latest and greatest version of the project/framework?

• The simple answer is that they don't get the framework from source control as code so all you really need is to make sure that the final binaries are there and easy to get. 
  You can either put the latest release's binaries in a known location in source control or in  known location on the network.
  There are usually two folders in that location:
•  Latest release Version (1.X or X.0)
• (if there was one)Previous release version with fixes (1.0.X)
• You can optionally make a folder for each older version you have with the latest fixes for it.

How do I use Branching in Team System Source Control?

TFVC provides robust branching capabilities. Individual files, complete directories, or projects can be branched. Even complete Team Projects and solutions can be branched.

Although there are several ways to access the branching functionality from Visual Studio 2005 Team System, one simple way is to select the folder in the Source Control Explorer window, right-click, and click Branch in the shortcut menu. This will result in a dialog box similar to that shown in Figure 2.

Figure 2. Branching

Users can browse to or enter the destination location in the source control repository to store the new branch. Figure 3 shows the Source Control Explorer after a branch operation.

Figure 3. Branch results

I just fixed a bug in the version 1.0 of my product, but we are in the middle of developing version 2.0! How do I add that fix to version 2.0 as well?

Usually, at least some of the changes made in a maintenance release will be rolled forward into a new version. The TFVC Version Control Merge Wizard, shown in Figure 4, can be used to move the changes from one branch into another. To access the Version Control Merge Wizard, select the source folder in the Source Control Explorer window, right-click, and click Merge in the shortcut menu.

As the Wizard is displayed, users can select and verify the source and destination of the merge, and specify whether the merge will include all changes since the last merge, or only selected changes. You can also select specific changesets to work with, representing all files checked in by a single user at a single time, or accept all differences between the two branches.

Figure 4. Merge Wizard                                         Figure 5. Merge resolution

During the merge process, TFVC will compare the differences in all of the selected files. When the files are different, the merge process will attempt to generate a current copy based on the the files in each branch. If the merge process is successful without user intervention, the merged files will be checked out and merged in the target. Note that TFVC can merge not only modified files, but also new files, deleted files, and even renamed files. If there are conflicts during the merge process that cannot be automatically resolved, the Version Control Change Wizard will request your assistance. You can choose to use either version of the file, however, as the final version, but in most cases, you'll probably choose to manually perform the merge. Manual merging displays the differences on a merge screen, with the file from the source branch on the left-hand side, and the file from the target on the right-hand side. You will have the ability to select the lines from each branch that you want in the final merged version. Figure 5 shows an example of the merge resolution screen.

Once the merge is complete, the resulting files will be represented as pending changes in your workspace, and you should test the merged version. Compile the projects and run your tests, to ensure that the merged version operates as expected, before checking it in to TFVC. If needed, additional files can be checked out to support the merge; TFVC handles changesets atomically, so all changes associated with the merge can be checked in as a single unit.

I'm used to using Subversion. Does branching strategy differ in Team System?

• In other words - should we follow the Subversion convention of creating a trunk and branches folder immediately under the project root?

• No. You branch the entire project root into a new version.

• I understand you *can* branch a file, folder, or project, but what *should* you ?
• Usually, branching a sub folder or file in a project can lead to a versinoing nightmare, as its really hard to maintain. It's almost always a good idea to have a whole version of the whole project/solution where your changes are not affecting other users and you don't have to worry about hidden sub folders who are branched.
•  Is it just as easy to branch your project, or is it easier to use the trunk/branches approach and just branch at the folder level?
  Branching is very easy at any level. But I'd recommend always branching at the project/soution root.

• I'm assuming the tags folder is not needed, since the labelling function does not require it.
• Correct.
  
  

How do I use Labels?

Version control systems typically use "labeling" to allow you to define specific files and versions of those files as a group. To apply a label on a branch or node in a branch, right click that tree node (or branch) and select "Apply Label".

Once the label has been applied, the files labeled together can be referenced as a whole later on in the development lifecycle. For example, labels can be created for nightly builds, allowing easy retrieval and reference of the file versions included in each build. Figure 1 depicts the labeling dialog box provided with Visual Studio 2005 Team System.

Figure 1. Labeling