16 June 2006

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.


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

Figure 1:

 Figure 2:


David said...

Why does this all sound so familiar. As usual Steve, you blow me away. Now, just make it work, damn it!

Steven St Jean said...

Thanks David! In case you were all wondering, David is my Dev lead (task master, task nazi, general pain in my ass) who has no input into my performance evaluation. :-)

Anonymous said...

The "magic" is something very helpful and it exists without any weird stuff since late 90s in products like star team and while developers on the ms platform were struggling to make VSS function as something more than simple storage even most of the open source products now have proper labeling as basic requirement. Oh yes TFS is a great improvement but still miles away from other products and still hides a lot of surprises or the weird stuff ;)

Steven St Jean said...

I agree that other programs have had this functionality for a while, but when your company will only work with Microsoft products, you make do. With that said, going from VSS to TFS for source control is a HUGE leap forward and on the right track. Microsoft will keep implementing "best of breed" features as the product matures.

chris said...

do you have any idea how to apply label by workspace using the tfs API?

Steven St Jean said...


I haven't worked with the Label API, but I suspect that the API to create a Label has a VersionSpec parameter. Passing "W" in this parameter is the standard way of denoting "use the current workspace".

Post a Comment