ALM Adventures

Part I: Why Branching Doesn’t Work
Part II: Labelling, Branching’s Poor Cousin
Part III: Apps Without Source Integration

In part one of this series I gave a detailed definition of what (in my opinion) constitutes a config file. There are grey areas, so I tend to use heuristics instead of cut-and-dried principles. Here are my rules-of-thumb:

• Config doesn’t get compiled into an application
• Config files are data rather than executable code
• Config is uploaded or copied over (in some way) to be made available to an application
• Config may be preferable to code so that business rules or settings can be amended without an application release
• Config files may be worked on by non-programmers: analysts, professionals and subject-matter experts
• Configuration files might be edited in Visual Studio but also plain text editors, custom-built apps, or a vast range of third-party applications

The last point is the subject of this post – how to access TFS source control from applications with no TFS integration. There are a few options, some better than others – depending on the particular circumstances. I will set out all the ones I have used or considered.

TFS 2010 MSSCCI Provider

MSSCCI is Microsoft’s clunkily-named standard for source control integration. It originated in the dark days of Visual SourceSafe but grew and gained support from many third-party applications. TFS does not use MSSCCI as it’s native source control API, but there is a free provider available which you install (in addition to Visual Studio or Team Explorer) on each client machine where you want to use it. Third-party apps with MSSCCI support can then be configured to talk to the TFS provider, which in turn talks to TFS.

MSSCCI is functional (it basically works) but is at the mercy of client applications. For example, Microsoft Access relies on MSSCCI and the integration logic can be frustrating: it might decide to check-out every object it has under source control, which it does one by one – a painfully slow experience compared to the simple operation of checking out whole folders using Visual Studio. Problems like that can be eased by following one of the check-out strategies below.

SvnBridge

I explored this option but didn’t use it, so can only suggest it as a possibility. SvnBridge is an open-source tool which allows client applications to access TFS as if it were Subversion. Effectively, it gets TFS to emulate Subversion. TFS doesn’t know it is being accessed by a client application built to work against Subversion, and the client application doesn’t know it’s not accessing Subversion – SvnBridge handles all the translation. Subversion is a popular open-source source control server and there are third-party applications with support for it, but not for TFS (e.g. BusinessObjects LifeCycle Manager). If you use one of those apps, give SvnBridge a try and let me know if it works out for you.

Note that if you are using Eclipse, Team Explorer Everywhere is a better solution.

No Source Integration

If your editor doesn’t have a source control integration that will talk the language of TFS, MSSCCI or Subversion, you can still use TFS source control but it will require some experimentation to figure out the best way to do it, and potentially some application-switching during the work.

First, you will need a way to execute source control operations. You can use Visual Studio or Team Explorer, which is fine if you already use it for other work. If you don’t know Visual Studio/Team Explorer and have no other need for it, it might feel like a pretty heavyweight option when you just want to get to TFS source control. In that case, the Windows Shell Extension that comes with TFS Power Tools works well. An added bonus is that applications that use a standard Windows file dialog should allow files to be checked out using the dialog itself – removing the need to switch applications.

Second, you should consider defining a strategy for how you are going to check-out from source control. If you are used to Visual Studio you may well ask why a “strategy” is necessary. Well, Visual Studio has various options for checking out files when you start editing them, which generally means you can forget about checking-out and just get on with the work. Without that you are going to have to decide what to check out and when. Here are the main possibilities:

Check Out On Demand

This means you check out files just before you need to edit them. That should be fine if your editor has a simple file-editing design, but some applications modify files behind the scenes at times and for reasons you cannot easily predict. For check-out on demand to work, you need to be sure the editor will complain if files are read-only and give you an opportunity to check them out. If you can’t be sure of that, this strategy won’t work.

Check Everything Out

This means you check out all the files that could possibly be modified, do your work, then check them all back in. TFS should detect which files have changed and only include those in the resulting changeset, and undo the checkout for files which haven’t changed. The downside is that you have to checkout files you will not modify, which might confuse other users.

Work Offline

This is an interesting option to consider if you don’t want to check everything out. It makes using TFS somewhat similar to a distributed revision control system such as Git or Mercurial. Visual Studio/Team Explorer will offer to take a solution offline automatically if it cannot connect to TFS, and give a manual option to go back online. The GoOffline extension exposes an option to go offline manually.

That’s fine if you are using a Visual Studio solution, but that’s unlikely if VS isn’t your editor. In that case, the TFS Power Tools provide a useful command line tool TFPT which can be used to work offline and go back online cleanly. Here’s a suggested process:

1. Use TFPT scorch to ensure there are no orphaned files in your workspace. This is necessary because when you go online later, add operations will be created for all files not under source control, replicating in source control any mess built under your local machine’s working folders.
2. Remove the read-only flag from all files which might be modified.
3. Modify the files as needed.
4. Use TFPT online to turn the edits into pending changes, then check-in as normal.
5. A final TFPT scorch /preview will check if there are any remaining differences between source control and the local file system.

Note: the complete TFPT syntax is not shown above. For example, you will normally want to include a restrictive filespec parameter to only include specific folders in the operations.

A downside to working offline is that file renames will be interpreted as a delete of the old file and an add of a completely unrelated file, so are best avoided.

Summary

Versioning config files can be a challenge but there is much to gain in traceability and risk reduction if you get it working smoothly. I hope these articles help you do that.

Part I: Why Branching Doesn’t Work
Part II: Labelling, Branching’s Poor Cousin
Part III: Apps Without Source Integration

Most of the information out there on TFS Source Control is in the realm of software development, concerning the intricacies of branching, merging, build automation and all that good stuff.

But what if you want to use TFS to version configuration files? By that I mean the many artifacts that don’t get get compiled into an application but control how it behaves – I’m thinking of report definitions, data mappings, calculation logic and the like. As a broad definition, I call “configuration files” any sort of soft-coded business rules or settings. Configuration files might be edited in Visual Studio but also plain text editors, custom-built apps, or a vast range of third-party applications. XML is a typical format, but config files can be any plain text or binary structure (although the latter is thankfully less common). Often, the files are generated and modified by non-programmers: analysts, business people, subject-matter experts, and specialists in the particular technology being used.

Configuration files are no less critical than the application itself; in fact they can be much more valuable – representing many man-years of effort analysing complex business logic into a machine-friendly format. Such important assets need the rigour of version control, but how should that be set up? A good branching strategy is the right place to start for application code, but branching is not great for incremental releases – which are commonplace for config changes. Here’s why:

• Granularity: merging works at the changeset level and gets ugly if you attempt it at a finer level. Even though it’s possible, I also try to avoid merging specific changesets and instead merge only whole branches – otherwise it can get difficult to track what’s going on. Bill Heys has a great post on why you should avoid Cherry Pick Merges.
• Versioning: branching works for application code because it ensures integration and testing of a consistent whole. For config, you often need to identify individual files or small subsets which will be released independently. Branching doesn’t help there.
• Conflicts: there’s no branching without merging and that means the possibility of conflicts. Traditional line-based code lends itself nicely to standard merge tools but XML, proprietary text formats and (especially) binary don’t fare so well.

If branching is out for versioning config files, what approach should be taken instead? I’ve seen organisations manage the problem by recording changeset numbers or copying files to shares. Neither are particularly satisfactory, not least because of error-prone recording and the heinous crime of duplication. In the next part of this short series I’ll look at labelling as an approach.