Why you should use a single TFS Team Project

October 4, 2013

I seem to be spending a lot of time lately trying to convince clients that a single TFS Team Project for the entire Enterprise is the way to go. To most people this seems counter-intuitive. They tend to create Team Projects for each actual Project and/or Team within their Enterprise. That just makes sense right? Indeed, if you look at most books on TFS they will usually have a section with guidance on Scoping Team Projects that usually recommends approaches that result in many Team Projects. My “go to” TFS book – Professional TFS 2012 – recommends choosing one of 3 approaches: Team Project Per Application, Team Project Per Release, or Team Project Per Team.

However, most TFS experts have come to agreement in the past couple of years that one big Team Project for the entire Company is often the best choice. The fact that this realization is relatively new explains why you won’t find much literature on it in published TFS books (hopefully that will change in the near future). Within the group of ALM MVP’s (which includes most people who would be considered TFS experts) most of us agree on this approach. And in fact most (all?) of the Microsoft TFS Product Team that I’ve talked to about this agree with the Single Team Project approach (they use this approach internally within Microsoft). Microsoft is actively introducing new TFS features that make this approach easier (more on that below). I also had a conversation with the authors of the Professional TFS 2012 book recently, and they all agreed that their guidance is outdated, and the next edition of that book should focus more on the Single Team Project approach.

The best source of information I’ve found to date on this topic is a handful of blog posts by Martin Hinshelwood (in chronological order):

What’s Wrong With Many Team Projects

The core of the problem is that introducing multiple Team Projects introduces constraints and limitations on what you can do, while providing little benefits. The perceived benefits of multiple Team Projects can usually be realized within a Single Team Project just through different mechanisms, and without the limitations that Team Project boundaries place on you.

What are the reasons that teams typically create multiple Team Projects? They do so because there are benefits to isolating and separating the various assets of each project/team, and creating a Team Project for each seems like the most intuitive way to achieve this. If you have two separate projects (by projects here I mean separate Business Projects typically with different teams working on them), then you typically don’t want members of Project A seeing or being able to modify the assets of Project B (by assets, I mean source code, Work Items, build definitions, etc). In addition to having security around the assets of each team, you also don’t want to have things like Reports, Backlogs, Queries, etc. showing assets from multiple projects. Each team should have it’s own separate backlog, reports, etc. And having a Team Project for each seems like an obvious way to achieve this.

However, the multiple Team Projects can cause significant hurdles if you ever wish to move data across a Team Project boundary. Team Projects are intended to isolate the data stored in each one, and there is no easy way to move some data from one Team Project to another. For source code, you could easily grab a copy of the source code in one project, and check-it in to another team project. However you would lose all history. I think you might be able to also do a Move command to move source code from one project to another, but again the History doesn’t come across (at least not in an ideal way). You can try to use the TFS Integration Platform (TIP) to migrate source code and history, however the TIP is horribly buggy and awkward to use. So much so that most TFS Experts I know refuse to even try to use it anymore.

The real problems though come when talking about Work Items. There is no obvious way to move Work Items between projects. Again, you might think the TIP is an option, but just like with source code, the TIP is crippled to the point of being unusable. Excel is a popular choice, export the WI’s from one Team Project into Excel, then use Excel to Import them into the other Team Project. There are some major issues with the Excel approach:

Any HTML fields (such as most description fields) will lose all formatting when being exported to Excel. This is usually unacceptable.
If the Work Item Type Definitions between projects differ then you may be in trouble. At a minimum you will have to go through a mapping exercise to determine how the Work Item Types and fields from one project map to fields in the other project. Then apply that mapping manually via Excel as part of the Export/Import process.
Most WI’s only have one valid “starting state”, then defined transitions from that state. So lets say your WI workflow enforces all WI’s start in “New”, then they must go to “Approved”, then finally to “Done”. Well how do you migrate WI’s that are already in the Done state? You can’t just Excel-Import them, because you’d effectively be trying to create a new WI directly into the Done state, which isn’t allowed. You’d have to first import them all as New, then transition them to Approved, then to Done.
You will lose WI History. This is often acceptable for most teams, but thought I’d point it out anyways.

To summarize, moving data (specifically WI’s) between Team Projects is complex and extremely time-consuming. It can be done, but usually requires you to hire a TFS Consultant to help you with it, and that can get very expensive. As a TFS consultant myself, you might think I’d be happy about this. After all, my company makes a lot of money helping clients with things like this. But believe me when I tell you, if I never have to do a WI migration ever again, I will be a happy guy.

There is still one last important point here to bring this all together, why would you ever want to move data between Team Projects? If you specifically created a Team Project for each project/team, then you should never need to move data between them right? Wrong! There are a number of reasons why the Team Project structure you create initially may not be appropriate 5 years from now. Here’s some examples of situations I’ve run into with clients:

One team starts a project, then gets handed off to a different team later
- A common example is where one team will develop some software, then hand it off to a different team for support/maintenance. That maintenance team is often responsible for many projects. The maintenance team wants all their work items for all their projects in one team project so they can see one “team backlog”, and roll-up reports across projects. They also may want to see backlog/reports for each specific project under them also.
You have a single Team that works on multiple Projects
- An example I’ve seen is you have 4 projects each in their own Team Project, but you have a shared BI team that handles all reporting/ETL/Data Warehouse tasks across all projects. Each project wants to see all of the project tasks together, and the BI team wants to see a consolidated list of work/backlog that belongs to the BI team. If each of the 4 projects have their own Team Project, then there is no way for the BI team to see a consolidated backlog of their work. If you create a separate Team Project for the BI team then there’s no easy way to move BI work items into that project, and if you duplicate them you run into another set of problems.

One last point that is useful to keep in mind, is that in general it is easier to split a team project up into multiple Team Projects later, than it is to start with many and combine them.

Structuring the Single Team Project

Going with a Single Team Project avoids most of the above problems. You will obviously never need to move Work Items (or code) between projects. But now you have the challenge of how to organize data within the Single Team Project to provide separation and isolation. This is accomplished mostly through a combination of using the Area hierarchy and Teams functionality. If we imagine we combine what used to be multiple Team Projects into a single team project, we end up with many “sub-projects” (not an official term) within the single Team Project. We can create a root Area for each sub-project, a TFS Team for each sub-project, and a root source control folder for each sub-project. Then we can use the Area field to filter all reports and queries. Each Team is tied to the related Area and is used to provide each Team/Sub-Project with it’s own Product Backlog. And Security can be granted based on Area and/or Source Control Path.

Areas

You should create a root area for each sub-project.

Iterations

Just like with Area hierarchy you should create a root node in the Iteration Hierarchy for each sub-project. Then you can maintain/manage the sprints/iterations for each sub-project separately.

Source Control

Create a root folder for each sub-project.

TFS Teams

Create a TFS Team for each sub-project. You can create a hierarchy of Teams, so each sub-project could potentially have many teams each with their own Product Backlog, then then roll-up into the parent team for that sub-project.

TFS Security Groups

You probably don’t want to use the default TFS Security Groups (Reader, Contributor, Build Administrator, Project Administrator). If you give somebody the Contributor role, it will make them a Contributor across every sub-project which probably isn’t desired. What you should do is create those 4 groups for each and every sub-project. So if you have 5 sub-projects, you should end up with 20 TFS Security Groups (plus the original 4 that aren’t sub-project specific).

Work Item Security

Grant the various sub-project Security Groups permissions for the root Area associated with that sub-project. This will ensure that only members of that team can edit/view WI’s that belong to that teams’ Area(s).

Source Control Security

Just like Work Items, you should grant the sub-project Security Groups permissions only to the root folder associated with that sub-project.

Build Agents/Controllers

Ideally you would have a Build Controller for each sub-project, then one or more Build Agents/Build Servers for each sub-project. Having separate build-agents/build-servers for each sub-project has long been a good practice. This is because a team typically needs admin rights on their build server, and often need to install various software/SDK’s/frameworks/etc. onto the build server to support their build process. This is different for each team typically, so you usually don’t want to share build servers between teams. The separate build controller recommendation is to avoid the possibility of a team accidentally using another team’s build server. If we were to share a Build Controller, it is too easy to accidentally configure the build to use any build agent regardless of “agent tags”, but this will have the unintended behavior of using other teams/sub-projects build servers/agents. By forcing me to pick a sub-project specific build controller when setting up a build definition, this makes it harder to accidentally run into this situation.

Build Definitions

When you have a Single Team Project, you are going to end up with a very long list of Build Definitions since all sub-projects Build Definitions will all be mashed together into one list. In 2010 there used to be a tool called InMeta Build Explorer that would allow you to introduce virtual folders to organize them. That tool does not work in TFS 2012/2013, however there are new features built into TFS/VS that make things more manageable. You can now filter/search through the Build Definition list right in Team Explorer, you can also setup My Favorites and Team Favorites to make your most common builds more visible.

Work Item Queries

You can create folders to organize Work Item Queries. You should create a root folder for each sub-project, then assign permissions appropriately so each sub-project Security Group only has permission to it’s relevant WIQ folder.

SharePoint Portal

If your team uses a SharePoint Project Portal then you will ideally want a separate Portal for each sub-project that only shows data for that sub-project. You can accomplish this by opening up the main Portal (for the Team Project) then create a new SubSite for each sub-project. When you create the SubSite pick the TFS Project Portal Site Template. Then open up the new Portal and you will need to edit each Web Part properties to ensure they all filter by the relevant Area for this sub-project.

Reporting

For the Reporting component of TFS no changes are needed. Most (all?) Reports include the ability to filter by Area, so you simply filter by the Area corresponding to the Sub-Project you are interested in.

What’s The Downsides to a Single Team Project

There are a couple downsides to doing the Single Team Project approach:

More Complex Administration

Adding a new sub-project requires a little leg-work to setup the proper security groups, root areas, WIQ folders, etc. You generally need to have a central TFS Administrator group/person that understands this process (and probably has it documented) and performs it whenever a new sub-project is needed. For example creating a new sub-project might consist of the following steps:

Create root Area
Create TFS Team
Create WI Query Folder
Create root Source Control folder
Create Team-specific Security Groups
Setup Build Controller/Agent

Process Template Customizations

Any customizations to the Process Template or Work Item Type Definitions will apply to every sub-project. This is by far the biggest problem. Any custom fields, or custom WI workflow states, or even custom WI Types will show up in all sub-projects. Microsoft appears to be rapidly introducing features that help mitigate this problem. Some examples of ways to mitigate this could be:

Ensure all changes go through a central TFS Administration group. This group can try to minimize customizations by suggesting alternatives (ex. adding a transition reason rather than an entirely new state). Also you can try to make then more generic (e.g. Adding a custom field to link to a bug in HP QC, you could call it Quality Center ID, or you could call it Reference ID then it can be used across other sub-projects to link to other external systems that maybe aren’t QC).
Work Item tags allow you to input metadata against a Work Item without needing to customize the WITD. This is *great* for the Single Team Project approach, because you can now enter sub-project specific information without needing to add customizations that affect other sub-projects. For example, if one sub-project really wants to designate some Bugs as HotFix, they might try to add a custom-field “HotFix?” with a Yes/No dropdown. The problem is, that HotFix dropdown will show up on all sub-projects, and other sub-projects probably would have no idea what that even means. Instead you could simply apply a HotFix tag to those WI’s in that specific sub-project only. Another example, is only a small number of sub-projects want to put a Priority field on Tasks (High, Medium, Low). Instead of a custom field they could simply use tags: “Priority: High”, “Priority: Medium”, “Priority: Low”.
Kanban Boards introduced into TFS recently allow you to define different Kanban states/workflows for each Team. This can often allow you to keep the Workflow states very generic just to support cross-project reporting. Then the team-specific Kanban states can be used to model each teams specific workflow.
Work Item Extensions is a new feature introduced to enable the KanBan Boards. It is not currently possible for anybody other than Microsoft to take advantage of this feature, but the TFS Team used Work Item Extensions to implement the KanBan features. It adds custom fields to WI’s dynamically based on the Area Path of the WI. In theory (and this is my hope), as this feature evolves it will allow us to define custom fields that only apply to a specific Area associated with a specific sub-project.

This Article Was Originally Published on Dylan Smith Geeks with Blogs

Need Help with Your TFS Team Projects?

If you’re ready to get started Team Foundation Server (TFS) or looking to take your existing TFS Team Projects to the next level, Imaginet is here to help. Our Imaginet-certified TFS and ALM experts have been working with the Microsoft TFS and ALM tools since they originated in 2005 and can help you get started with any of your TFS or ALM initiatives. To find out more, schedule your free consultation call with Imaginet today.

Thank you for reading this post! If you enjoyed it, I encourage you to check out some of our other content on this blog. We have a range of articles on various topics that I think you’ll find interesting. Don’t forget to subscribe to our newsletter to stay updated with all of the latest information on Imaginet’s recent successful projects

Imaginet

Imaginet is one of the earliest Microsoft partners in Canada that continues to push the boundaries of innovative software solutions delivered with Microsoft technologies. Boutique in size and world-class in ability, Imaginet’s full-time, on-shore consultants have provided implementation and adoption services for Azure, Microsoft 365, Power BI, and .NET to over 1,500 organizations.

discover more

Let’s build something amazing together

From concept to handoff, we’d love to learn more about what you are working on.
Send us a message below or call us at 1-800-989-6022.

Why you should use a single TFS Team Project

SQL Saturday Part 2: Learning About Microsoft Fabric

My Trip to SQL Saturday Atlanta (BI Edition): Part 1

Enabling BitLocker Encryption with Microsoft Intune

Let’s build something amazing together