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.

In the first part of this series I explained why branching might not be the best strategy for versioning “configuration” files. These are items that control or influence an application but aren’t an integral (compiled) part of it, and often have a different development and release cycle. In this part I offer a solution and then, ahem, gripe about the tooling for it.

The solution is labelling – a completely flexible way of identifying specific versions of specific files. The concept is very similar to tagging photos on a photo-sharing site or posts on a blog. The label itself is a simple text string and can be anything you like. You can apply one or more label to any version of any files. Unlike changesets, which cannot be modified after creation, labels can always be updated. Unlike branches, which are driven by changesets, labels don’t push you into a rigid work flow or strategy. About the only thing you can’t do is apply the same label to more than one version of the same file, but I can’t imagine a realistic scenario where you would want to do that.

So that’s sounding nice and simple, right? Just label up the config files you want to release together, modify the labelled files if something changes or needs fixing, and when it’s all ready get the labelled files out of source control and deploy. Easy. Well, it would be if the Visual Studio support for labelling wasn’t so cursory. It seems like all the effort went into branching, and labelling was dismissed as the poor man’s configuration management – a clumsy oaf stamping random files with ill-named tags, compared to the sophisticated beard-stroking intellectual that is branching. Don’t get me wrong, branching is great, but not everybody is versioning branch-friendly application source code (and dependant artifacts) alone.

Here’s what’s not up to scratch in the Visual Studio 2010 support for labels:

• The Source Control Explore context menu option Apply Label doesn’t apply an existing label, it creates a new one. The dialog that pops up is called New Label with a button named Create so it knows its own purpose, even though the menu item doesn’t. Understandably, people try to use this to apply an existing label to additional files. When they do (and don’t read the next dialog carefully) they wipe out the existing label completely and start from scratch with a new label. One mistake like that is enough to convince people labels are too risky to depend upon.
• Apply Label only allows one file or folder to be selected. As Apply Label can only be used once per label (see above) why not let users label multiple files at the same time?
• You can’t select files in source control and apply an existing label.
• You can’t select a version of a file from the history and create a label or apply an existing label.
• You can’t easily apply a label to every file in a changeset.
• The label editor (the only way to modify a label) is hidden all the way under File –> Source Control –> Label –> Find Label. Yes, it’s also accessible from the label tab of a file’s history, but to get to a specific label that way you need to know a file that has it applied and navigate to it.
• The label editor has a Change Labelled Version button but a more direct Update to Latest feature would be nice – much of the time when you change the labelled version that’s what you want to do.

There’s a lot that could be better, but despite it all the TFS labelling implementation is sound at it’s core, and despite its awkwardness the tooling is usable. If someone could crank out a VS extension that fills the GUI gaps it would be perfect. Watch this space…

Once you have your label correctly applied you will want to get the right versions of the right files so they can be deployed. You can simply Get the label from the root of a workspace to clear out other files and get the labelled files alone. You probably won’t want to use your normal workspace for that, as the operation may well interfere with normal work (and vice versa). You could manually create a second workspace for getting labels, but I find a batch script is cleaner:

@ECHO OFF
SET ProjectCollection=http://MyServer:8080/tfs/MyProjectCollection
SET TeamProject=MyTeamProject

REM Prompt for label name
SET Label=
SET /P Label=Enter a label to get from TFS:
IF "%Label%"=="" GOTO Exit

REM Setup workspace (fails non-destructively if it already exists)
C:
CD \
MD TFS
CD TFS
MD DeploymentWorkspace
CD DeploymentWorkspace
"%VS100COMNTOOLS%..\IDE\tf" workspace /new /collection:%ProjectCollection% DeploymentWorkspace /noprompt
CLS

ECHO Getting labelled files to C:\TFS\DeploymentWorkspace...
ECHO.
"%VS100COMNTOOLS%..\IDE\tf" get . /version:L"%Label%"@$/%TeamProject% /force /recursive

REM Check if label exists (error TF14064)
"%VS100COMNTOOLS%..\IDE\tf" dir . /version:L"%Label%"@$/%TeamProject% /recursive >LabelContents.txt 2>&1
SET /p LabelContents=<LabelContents.txt
DEL LabelContents.txt
SET LabelContents=%LabelContents:~0,7%
IF [%LabelContents%]==[TF14064] GOTO Exit

ECHO.
ECHO Copying to Desktop folder %Label%...
CD "%USERPROFILE%\Desktop"
MD "%Label%"
CD \TFS\DeploymentWorkspace
xcopy %TeamProject%\* "%USERPROFILE%\Desktop\%Label%\" /s
ECHO.

:Exit

pause

That’s it! The next part looks at the challenges of versioning config files that are not edited within Visual Studio.

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.

I think “Project Collection” and “Team Project” are both quite confusing terms, bordering on misleading. If you jump right into TFS without spending time on the books, blogs and ALM Rangers material you would naturally set up one Team Project for each of your, well, projects, and maybe use Project Collections to group together handfuls of related projects. My advice: that’s the last thing you should do.

Instead of taking the names at face value, look at them like this:

Project Collection = Organisation

Project Collections cannot see each other at all. They are a way of having complete separation without needing multiple installations of TFS (as you did prior to the 2010 version). Each Project Collection has its own SQL Server database and there are very few reasons to have more than one, namely:

• Portability: You can quite easily detach a Project Collection and move it to a different TFS instance
• Performance: If SQL Server starts creaking you can split Project Collections for performance reasons (but explore all other performance improvements first)
• Law: If there is some regulatory reason why your data must be kept completely separate, multiple Project Collections will do that for you.

If in doubt, remember: you can split a Project Collection with no loss of data but you can’t join them together again. (OK, you can use the TFS Integration Platform to migrate them together but you use fidelity, as it “replays” the source and work item history into the new database, and there are elements that can’t be migrated at all).

Summary: Unless you have a very good reason not to, have one Project Collection per organisation.

Team Project = Team

Team Projects live together in a Project Collection, and can see each other transparently. However, each Team Project has entirely its own configuration in security, source control and work items. If you have a team that works on different projects, with team members moving regularly between projects or even working concurrently on multiple projects, the administrative burden of having a separate Team Project for every real project is likely to make your head spin.

Team Projects are good for separating teams or processes, which are hopefully the same thing – you don’t want one team following more than one process, do you? Sure, if you have a large project with a distinct team and it’s own way of working then a new Team Project is what you need – everything can be configured and customised just how that project needs. Otherwise, go with the “Project of Projects” approach outlined expertly by Martin Hinshelwood.

Summary: Have one Team Project per team, not per project.

To be effective, the team needs to find a way to verify each piece of work against the DoD. To keep the process lean, it helps to build verification into the process in as simple a way as possible. There are different ways of setting this up in TFS, for example work items could be customised to include fields for each part of the DoD, and those fields could become mandatory when setting the status to Closed. However, this approach requires the team member who closes a work item to vouch for all the work that went into it – work that may have been done by several people over days or weeks.

Instead of using work items directly, I believe the best way to track the DoD is at two “gates”: check-in and build. Check-ins should be small and frequent, and with continuous integration builds run on every check-in, so this gets the tracking of “done” as close as possible to the execution of individual pieces of work (i.e. tasks). This way, check-in policies and the build provide automatic checking, while check-in notes can be used to verify elements of the DoD which cannot be automated. Here’s an example DoD and how it can be tracked using those mechanisms:

Example Definition of “Done”

1. Code builds
2. Code has been reviewed
3. Code is covered by unit tests
4. Code changes can be traced to requirements
5. Unit tests pass

Check-in Policies

These are a great tool to maintain check-in standards. As previously posted, check-in policies can be overridden but it’s easy to set up an alert to detect that. The TFS Power Tools are a must-have here as they provide a number of check-in policies including the crucial Custom Path Policy – which scopes other policies to specific folders. I find the following policies very useful:

• Changeset Comments Policy: requires a comment for every check-in. These should be used to provide a high-level summary of what has changed rather than why (why is captured better with a work item link).
• Work Items: requires a work item to be selected on check-in. This enables traceability to requirements. The policy can be scoped to a specific set of work items using the Work Item Query Policy but I have found this to be over-engineering.
• Forbidden Patterns Policy: prohibits certain files being checked-in. Best used with the Custom Path Policy and a consistent source structure so the prohibition can be scoped to certain folders. For example, you may prohibit compiled DLLs being checked into source code folders.

Other policies such as Builds, Code Analysis and Testing Policy are in my opinion too restrictive or awkward to use, or are intended to meet requirements that are better met by automated builds.

Check-in Notes

These are simple text fields that can be customised, and made mandatory, for each team project. For example, a code (or peer) review can be verified by making the Code Reviewer field mandatory. This applies to all files in source control, so the team would need to decide if it’s OK to enter “n/a” for non-code check-ins or if all check-ins should be reviewed (including dependencies, documentation etc.) Shelvesets can be used to defer check-in and allow a team member to pick up a potential changeset for review.

Build

The TFS build system offers the greatest potential for customisation. Out of the box it will verify that code builds, and (if you use MSTest for unit tests) run the tests and calculate code coverage. There is an option in the default template to fail the build if any tests fail, but to take it further you need to customise the work flow. This could be used to fail the build if code coverage has dropped since the previous build, or bring virtually any other metric into the mix – enabling you to extend the build process as needed to match an extended DoD.

A really powerful option related to Build is Gated Check-in. This reverses the normal sequence so that build happens before check-in and if the build fails the check-in is rejected. This ensures that not only is the DoD tracked, but that code that does not meet it can never reach the code base and impede other work.

Good as these are, there is much they don’t do well (or at all). I have found the additional tools below very helpful.

There are many other add-ins and tools out there, but these are the ones I use with some frequency. I’ll update the table if I add others to my regular TFS toolbox!

A little while back I came across a bug, in Alerts Explorer or the TFS events system, which had a very irritating effect – spam! It took a good while to diagnose but a fairly simple workaround was found. Here’s the scenario…

Imagine you want to receive an email whenever a work item is assigned to you – a very common requirement. The obvious way to set it up is like this:

This alert definition should send an email to Joe Bloggs whenever a work item is assigned to him, except for when he assigned it to himself. And it will do exactly that, most of the time. Unfortunately it will also send an email when a link is added to a work item already assigned to Joe Bloggs, with no other changes made at the same time. Imagine that another user is linking a handful of work items, one at a time, to another work item that is with Joe Bloggs. Poor old Joe will receive one email for every link added!

To diagnose this issue it’s necessary to understand the TFS eventing system. It basically works as follows:

1. Every time an event happens (the “WorkItemChangedEvent” in this case) an XML document is generated by the TFS Eventing system.
2. TFS sends the XML to all subscribers to that event, which in this case includes the Alerts system.
3. The Alerts system applies the filter defined for each alert to the event XML to identify which alerts are relevant.
4. For each alert match, an XSLT transformation is applied to convert the XML to HTML, and an email is fired off.

So far, so good. So why does this alert also fire off emails when the only thing changed is a work item link? There are two parts to this puzzle. The first is the Filter Expression for the alert. Alerts Explorer handily exposes the underlying filter generated by the GUI on a second tab:

This is actually a partial XPath expression, which is applied against the event XML. If there’s a match then the alert is sent. This filter amounts to a query that (to paraphrase) says CoreFields/AssignedTo/OldValue is not “Joe Bloggs” and CoreFields/AssignedTo/NewValue is “Joe Bloggs” (the ChangedBy field isn’t part of the problem, so I’ll ignore it).

The second part of the puzzle is the event XML itself. Unfortunately this is much more difficult to come by than the Filter Expression. There are various methods by which you could get at the XML, but I found a simple solution was to replace the XSLT transformation which would normally generate a nicely formatted HTML email message with one that simply spits out the source XML as HTML, so you can see it in the resulting email. Of course you shouldn’t do that in a production system, as your users are unlikely to appreciate emails containing raw XML!

Quick instructions on how to replace the alert XSLT:

1. On the TFS application tier go to this folder (or equivalent) – C:\Program Files\Microsoft Team Foundation Server 2010\Application Tier\TFSJobAgent\Transforms
2. Rename WorkItemChangedEvent.xsl to WorkItemChangedEvent.xsl.bak
3. Download XMLToHTMLVerbatim.xsl (Copyright 2002 Oliver Becker) copy it into the folder and rename to WorkItemChangedEvent.xsl
4. Edit and save work items and inspect the resulting emails (there may be a two minute delay as alerts are queued)

With that in place you can see that the XML generated when only adding links to a work item looks like this:

<WorkItemChangedEvent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 ...
 <Subscriber>UK\JoeBloggs</Subscriber>
 ...
 <ChangeType>Change</ChangeType>
 <CoreFields>
 <IntegerFields>
 <Field>
 <Name>ID</Name>
 <ReferenceName>System.Id</ReferenceName>
 <OldValue>0</OldValue>
 <NewValue>192</NewValue>
 </Field>
 <Field>
 ...
 </IntegerFields>
 <StringFields>
 <Field>
 <Name>Work Item Type</Name>
 <ReferenceName>System.WorkItemType</ReferenceName>
 <OldValue />
 <NewValue>Bug</NewValue>
 </Field>
 ...
 <Field>
 <Name>Assigned To</Name>
 <ReferenceName>System.AssignedTo</ReferenceName>
 <OldValue />
 <NewValue>Joe Bloggs</NewValue>
 </Field>
 <Field>
 <Name>Changed By</Name>
 <ReferenceName>System.ChangedBy</ReferenceName>
 <OldValue />
 <NewValue>Fred Smith</NewValue>
 </Field>
 ...
 </StringFields>
 </CoreFields>
 <AddedRelations>
 <AddedRelation>
 <LinkName>Affects</LinkName>
 <WorkItemId>358</WorkItemId>
 </AddedRelation>
 </AddedRelations>
</WorkItemChangedEvent>

Even though the assignment has not changed – the work item has been with Joe Bloggs the whole time – the OldValue for AssignedTo is empty. The NewValue correctly says Joe Bloggs, so the filter is met and an alert sent! The eventing system detects the change but the XML has inaccurate values, so it appears that a different change occurred (I have reported this on Microsoft Connect).

The workaround (which is thankfully much simpler than the investigation) is to modify the alert definition to also reference the XML’s ChangedFields. These fields are not populated in the example above, but are present in every other type of work item change. It seems a little odd that Alerts Explorer does not reference these fields when you use the Changes To or Changes From operators, because it does when you use the Changes operator. So all you need to do is add a Changes operator to the alert definition like so:

The filter expression now includes AssignedTo within ChangedFields as shown below, ensuring you don’t get the alert unless that field really has changed.

I suspect the fix for this is a change to the TFS eventing system to properly populate the OldValues, or a change to Alerts Explorer to reference ChangedFields when using the Changes To/From operator (or both).

Although it’s painful to debug this issue, it gives an interesting insight into the system and hopefully this post will help others figure out why TFS is spamming them!

Alerts Explorer allows very sophisticated filters to be set up, but that power can be confusing. I have found that in a development team lead role just two special alerts provided the oversight I needed. Here’s how to set them up.

Alert 1: Check-in Policy Override

Check-in policies (along with folder security) are invaluable for source control management – they can enforce check-in comments and linked work items, and prohibit specific file types being checked-in. However, users can simply override the check-in policy! In one way this is helpful, because it allows work to continue past an overly-restrictive policy, but in every other way it’s madness – people can ignore your carefully constructed policies whenever they like.

Fortunately there is a good compromise – you set up an alert telling you when the check-in policy has been overridden. That way, the user can override the policy if they think they really must, but you get to review what happened and take action if necessary. I found that simply telling people that you get an alert when the policy is overridden was a sufficient deterrent 99% of the time.

This alert is a slight modification of a template that comes with the TFS Power Tools. Note that all source control users must have the power tools installed if you are using any of the check-in policies that come with the power tools, or you will receive an alert every time they check-in (which is quite useful, as you can then tell them to install the power tools!)

Alert 2: Build Failure

The Build Notifications tool that comes with Visual Studio is OK, as it generates system tray alerts that are near-synchronous with build completion. But it’s not much help if a build failed an hour ago or overnight. An email alert can cover this instead.

Note that I have not simply chosen StatusCode = Failed as I also want to be alerted on builds that are “partially successful” i.e. that have test failures. I’ll give users the benefit of the doubt on Stopped builds and assume that builds are only stopped for valid reasons. You may decide differently for your team.

First, some background… before TFS 2010 you could link work items together, but couldn’t specify what their relationship was. In TFS 2010 you can do that, because there are different link types to choose from including parent/child, successor/predecessor and related. As you may guess from the names, each of these link types has rules that define how they can be used, called a topology. For example:

• Parent/child uses a tree topology – meaning that relationships must be one-to-many and cannot be circular. So a child can only have one parent (only in the field of computing could that statement pass without bemusement).
• Successor/predecessor uses a dependency topology – meaning that relationships are many-to-many but cannot be circular, and the direction determines what name is given to the link.
• Related uses a network topology – meaning that anything goes, including circular relationships, and the link has the same name regardless of direction. It indicates that work items have something in common without saying exactly what that is.

You can use the link types that come with TFS 2010 to define richer relationships between work items, but you can also create new custom link types.

You define a custom link type in an XML file like so:

<?xml version="1.0" encoding="utf-8"?>
<LinkTypes>
 <LinkType ReferenceName="MyCo.LinkTypes.Releases" ForwardName="Releases" ReverseName="Released By" Topology="Tree" />
</LinkTypes>

And upload it into TFS using witadmin:

witadmin importlinktype /collection:http://myserver:8080/tfs/DefaultCollection /f:"LinkType_Releases.xml"

This particular link type was created so TFS could be used to track complex configuration changes, linked together under a new Release work item type. The thinking at its creation was that one work item could only be linked to one Release, so the Tree topology was the right choice. It later turned out that under some circumstances one work item could be included in multiple Releases – which is prohibited by the one-to-many rule of the Tree topology.

So the logical decision is to modify the custom link type to the Dependency topology, which (sadly) results in:

TF212018: Work item tracking schema validation error: TF201001: Cannot change topology for a link type MyCo.LinkTypes.Releases, it has already been defined.

Ouch! Even though I want a less restrictive topology, TFS prohibits the change. There is no simple way to get around this – getting the change in place requires a tedious workaround such as:

1. Rename the existing link type
2. Create a new corrected link type
3. Change all of the work items using the old link type to the new link type
4. Delete the old link type

I can understand that changing a link type to a more restrictive topology could invalidate existing links, so it makes sense to prohibit that change, but why not allow a change to a less restrictive topology – which cannot possibly cause that problem?

I’m guessing that Microsoft either didn’t think of this scenario, or thought it too rare to accommodate. Either way, the lesson is that custom link type topologies should be chosen with great care and, if in doubt, choose the one that is less restrictive!

Before leaping in, ask yourself the following:

Are we using the right process template?

Using a different process template could give you what you need in a simple and well-proven package. This requires you to create a new Team Project, because you can’t change the process template for an existing team project. (Although you could get away with it if you haven’t used Work Items yet, by importing Work Item Type Definitions etc.)

For example, the CMMI template comes with Risk and Review WITs, along with detailed guidance on how to use them for risk management and code reviews respectively. By the way (and contrary to popular belief) the CMMI process template does not preclude you from using Agile methodologies, you can absolutely do Agile (and Scrum) with the CMMI template – we do. (Although it does lack some resources available from the Agile and Scrum templates such as iteration planning workbooks). Work item fields belong to the Project Collection, not Team Projects, so whichever template you adopt you can easily add fields you like from other templates.

Do you understand your process template?

There is very detailed MSDN guidance on each template here:

• Agile
• CMMI
• Scrum

It may be some time since you last read the guidance, or you may have skipped it completely, so take time and understand how the templates are intended to be used. This may sound like preaching, when you just want to make a change, but it’s not unusual for a team to make an (apparently) must-have modification only to realise later that their needs were already met – they just hadn’t realised it. You could even end up reversing you change once you understand the template properly – a situation I have seen several times.

Is it you who needs to change?

The TFS work items system defines and tracks the day-to-day software development process for your team, so it’s crucial to use it well. Any team could adopt TFS and carry on working exactly the way they did before – using, abusing or ignoring the system as required to get their work done the old way they are used to.

It’s easy to think along lines like “TFS needs to change to fit the way we work” but make sure you don’t miss out on process improvements by changing the way you work instead. Question why you work the way you do and don’t accept that it’s right without some detached evaluation first. Some working practices are laid down diligently to meet the needs and technology available at that point in time, while others spring up in reaction to particular problems, or develop organically. Requirements, technology and the work you do can change quickly, and the process that was right even just a couple of years ago may not be right now. Don’t be afraid to adapt yourself rather than your technology – the default template may define a better process than the one you have now.

Does the naming fit?

Language is far from precise, and trying to distil complex concepts into one or two words is extremely difficult. For example, the CMMI state workflow of Proposed/Active/Resolved/Closed is simple, but can be a huge source of confusion – does Active mean someone is working on it or that just that the work is ready to be worked on? Does Resolved mean the work has been completely finished (a valid interpretation by the dictionary definition) or just that it has been implemented and we need to verify it?

Likewise, words such as “issue” can be vastly overused and the Issue work item type could mean almost anything, rather than the blocker or impediment it is intended to be.

Before making wholesale changes, consider if a simple renaming could meet your needs. You can rename almost anything in TFS process templates – fields, work item types, layout labels, states, transitions etc.

But if it does need to change…

Then absolutely change it!

The message here isn’t “never change the process template”, it’s “understand it, then make changes in the right place”. There are many valid reasons to change the process template, and you should never be held back by a template that isn’t working for you.