Why I Like Labels in TFS Version Control

Hi again,

If you were expecting Part II of the TFS Team Build series, sorry… I’m still working on it.  I had to write about this stuff today because I think it is VERY cool.  As you all know I’ve been playing around with continuous integration and code generation the last few weeks.  One of the issues I came across in the VSS world was that I would have to do the following:

  1. Clean all source folders
  2. Label VSS source code at tip (latest)
  3. Get source code to build by label
  4. For each Solution
    1. Check out code gen files
    2. Run code gen
    3. Check in generated files
    4. Move label on code generated files to new version
    5. Compile
  5. Run tests
  6. Stage binaries
  7. Package

As you can see, to get a reproducible build, I had to label the tip (latest) at the start and then had to label after each code generation step to move the newly generated files into the existing label.  This was necessary to ensure that we could pull the code that we had built and tested out at any time and rebuild it to the same state.

Under TFS Version Control you have a myriad of ways to apply a label.  You can apply to the “tip” (latest version) of version control, a specific changeset, a specific date or even another label, but the most interesting method of application is by workspace.  Labeling a workspace basically means that a label is applied in version control to the version of the files that you currently have on your client PC.  That’s pretty damn cool!  Let’s see VSS do that!  This insulates us from changes made to version control after we Get our code for the build.

Background:  TFS Version control is able to perform this little bit of magic because whenever you Get files to your client PC through a workspace it logs the filename, and version on the server so it knows what you have without asking you. 

This is also the reason that if you delete a file from your drive and then do a Get Latest, TFS comes back with an “All files are up to date” message.  In this case only a Get Specific Version with the Force Get of File Versions Already in Workspace option checked will bring your file down from Version control. 

Why is this cool?  Imagine that you are building a Continuous Integration system (with or without file manipulation and check-in).  What this allows you to do is the following (assume the code generation task from the prior list):

  1. Clean all source folders
  2. Get source code to build from the “tip” (latest) of TFS Version Control
  3. For each Solution
    1. Check out files
    2. Manipulate files (code generation)
    3. Check in changed files
    4. Compile
  4. Run tests
  5. If all tests pass, label all the files in version control at the version you have in your workspace
  6. Stage binaries
  7. Package

This means 2 things: First, you only have to label once per build and be assured that your label correctly reflects the code that you have built.  Second, you only have labels on builds that have passed all of your tests.  In this way, every labeled version is a good build so it’s easy for developers, testers or buildmasters to find good builds.

BTW, TFS Team Builds use the label by workspace method.  They just label prior to compilation as opposed to labeling after the build passes.

So Steve, How do you do it? 

  1. Get the source code that you want to label from version control to your local machine.
  2. Go to the Source Control Explorer in Visual Studio and right-click on item that you want to label.  This could be anything from a Team Project version control root to a single file.  It looks like you have to have only one item selected.  If you select multiple files, the “Apply label…” menu item is grayed out.
  3. In the context menu, select “Apply Label…”  the dialog in Figure 1 appears.
  4. In the “Version” combo select “Workspace Version”.  The “Workspace Version” text box appears.  It should default to the current workspace, so leave it alone.
  5. Click the “Ok” button.  The “Apply label for [item selected]” dialog (Figure 2) appears.
  6. Enter a name for the label and an optional Comment.
  7. Weird part: At this point if you need to add or remove files from the label, you can do so in the “Items” list by using the “Add…” or “Remove…” buttons.  Why didn’t Microsoft just allow us to make multiple selections in the first place (see #2 above) as well as letting us tweak the list from here?
  8. Click the “Ok” button and your label is applied.

References: 

MSDN – How To: Apply Labels
MSDN – Label Command
Microsoft.TeamFoundation.Build.targets -> CoreLabel target

Figure 1:

 Figure 2: