Working within a single Team Project with Team Foundation Server 2012

Working within a single Team Project with Team Foundation Server 2012 provides a lot of benefits. There are however many design consideration for working within a single team project and we need to consider all of the complexities that is entails.

One of the customers that I work with has over 200 departments in their organisation that are currently using TFS and each one of those supports one or more teams building multiple products in a single team project. They do not give any of those divisions “Project Administrator” on their Team Projects and in itself sounds like a management nightmare. Why? Well that means that ANY security change needs to go through a central administrator. In order to support this type of situation we need to create some workflow for making sure that everything is setup correctly and some automation so that we can build out the correct permissions without needing direct access. But before we do that we need to look at all of the angles and design our implementation to take advantage of the features in Team Foundation Server 2012.

The TfPlugable Team is part of the TfsExtension Team Project
Figure: The TfPlugable Team is part of the TfsExtension Team Project

Unfortunately the implementation of Team Project is a little flawed as it imposed some technical restrictions that are difficult to live with and if you look at the top items on the Team Foundation Server User Voice site you can begin to get a handle on the issues. Even worse, the inability to rename your Team Project is the least of your worries; You can query across Team Project but that’s not the default; You can’t load cross Team Project queries in Excel; You can’t move a work item created in one Team Project to another.

Ultimately we should always have been working in a single Team Project even if we did not know that we were supposed to.

What you describe [single team project] is what we generally do internally and what we recommend. We make very heavy use of area path to categorize the work within a larger project.”
Brian Harry, Microsoft Technical Fellow & Product Unit Manager for Team Foundation Server

Design considerations for Working within a single Team Project with TFS 2012

Because Team Foundation Server is a group of tightly coupled but flexible services it does not force you into any one way of working like many other tools. So we do need to think about how we are organising our Source Control, Areas, Iterations and Teams to understand how we might be impacted across the board and what our automation workflows are. In our deliberations we have three main entities that we need to cater for:

  • Team – This automatically creates our Security Group that we will be using and has an Administrator is set for that group
  • Product – When you create a product you will likely need both a Source Control location for that Product to reside and an Area to contain the related work items. You can break your product down into components inside that Area and you may have branches under the Source Control folder but the layout and organisation should be up to the product owners and the team.
  • Project – A Project is something time limited so lends itself to an Iteration within TFS but you would not prescribe the cadence. Your Project many be waterfall or Scrum or Kanban and it should not matter.

There many be other things like Work Stream or Cost Code or other flat categorisation elements that you might want to use in your single Team Project. These can easily exist as drop-down-lists on the work items that exist in our requirement work item and don’t necessarily impact the workflows described above.

“Using areas in existing team project instead of creating a new team project (a.k.a. “prefer small number of big team projects over large number of small team projects”) has been established best practice for long time. Microsoft works that way internally and they recommend everyone should. We use it internally and all of our partners have been thought to use it as well.”
Ognjen Bajic, Visual Studio ALM MVP, Product Owner of Team Companion at Ekobit

Note You may want to have Teams own projects. If you have many projects and your teams own more than one at ay time you can use Teams without areas but instead of having a list of “Teams” you create a list of Projects and define which Teams own which projects in the Team configuration.

Team in a single Team Project

In Team Foundation Server 2012 everything within a Team Project revolves around a new feature called Team. A Team is ultimately a security group with a bunch of meta data and features hanging from it (Yes..unlike a Team Project you can rename a Team). In the agile world a “Team” represents a long running tight group of individuals that operate more like a sports team but building software. If you are not an agile team, or in that half way phase of trying to get there, then you might also think of “Team” as something more akin to “Project”. In that scenario you have a time limited group of individuals that operate either full or part time together only for the duration of said “Project”. While the latter would reduce the effectiveness of the Team and would thus be considered a dysfunction it can often be a reality of that awkward transition towards agility.

Adding teams working in a single Team Project
Figure: Adding teams working in a single Team Project

In either of these cases you can use Team as the thing that you create instead of Team Project. This Team gives you the bucket of compartmentalisation of work items while allowing those teams to interact in a tightly integrated manor as needed. You also gain the ability to move work items between teams and query cross team with ease. If you are working on a large software project you might have many teams on the same cadence and while you want them to have their own space they still need to integrate and report things together. Or you might have multiple cadences across multiple products and only teams working on the same product work in the same cadence. The Team feature gives you the flexibility to choose you own way and adapt as you grow.

Product in a single Team Project

Product is a thing that you version, create instances of, and then deploy to production. A version of this entity is what is promoted through your release process although you may need to break it down into components if it is really big. Some of your Products will be built in an agile fashion and release at least every 30 days while other will have longer iterations and be delivered less regularly. We need to come up with some way to wrap all of our Products regardless of the things that may be different between them. This interface will allow us to control creation and security by following a pattern that we can automate.

Area as Product when working in a single Team Project
Figure: Area as Product when working in a single Team Project

Considerations for your Product hierarchy:

  • Area Hierarchy – Within a Product we may have components or trees of components. Area support roughly 254 nodes per level and can be 11 deep so there are limitations to consider. You will always see all of the nodes and you can control security at each and every level.
  • Version Control Hierarchy – Each of our Products are going to have source code and other associated files. We need somewhere to keep them in isolation now that we don’t have Team Project so that we can control permissions and isolation.

Note If we maintain the level at which Product exists in both Area hierarchy and in Version Control then we can easily automate against it.

Note The same rules apply and you can use the same physical organisation as Project of Projects with Team Foundation Server 2010.

Project in a single Team Project

Project is that time limited group of deliverables that results in a new release of one or more Products. The Project may contain many releases or it may be one. A Product may have many Projects or even just one that contains many releases. We need a model that supports whatever our teams need and that is reflected in Iteration Path.

Iteration as Project cadence when working in a single Team Project
Figure: Iteration as Project cadence when working in a single Team Project

Considerations for Project hierarchy:

  • Iteration Hierarchy – Creating a hierarchy in Iteration gives us the ability to have single or multiple strands of time allocation. It can be split by Team or Product or Project and each of those things can have their own cadence. That cadence should not be determined arbitrarily by the process overlords, but instead we can allow each unit to determine their own cadence.


While I can’t hope to provide a method of using Team Foundation Server 2012 and its features that work for everyone I am trying to create a versatile wrapper for any sort of work that is done within a Team Project. Ideally you would have only a single Team Project within your Team Project Collection and using Teams, Area Hierarchy and Iteration Hierarch we can map to but not into Teams, Products and Projects. The hope is that this wrapper described in the design guidelines above can allow you to automate against the TFS API’s and thus minimise your administration overhead while providing that versatility. There is an awesome post on backlog grooming that shows you how to configure more advanced team organisation in Team Foundation Server with Teams and there are plenty of other options.

If you are using Team Foundation Server already then there may be a lot of work that needs to be done to reorganise your existing work before you start as well as implementing your new and specific workflows based on the generic implementation above. This is however the only way for an enterprise, or really any organisation with more than one team, to take advantage of the new Agile Project Planning features of Visual Studio Team Foundation Server 2012.

It can however be a lot of work and the great god Murphy can strike at any time. Plan carefully and make deliberate and tested changes to TFS and your structure to support this.

  • We’ve been wrestling with this issue ourselves. We made the classic mistake of many team projects (actually we went even further down the rabbit hole of craziness than that, but the details don’t matter so much) and we now realise that we really need one single team project.

    One issue we see though is that a lot of the configuration (workitem workflow, checkin policies, etc) is at the project level. For our main product code, we have a set of policies that need to be satisfied and a process to follow with each checkin, but we don’t necessarily want that on our smaller internal projects (prototypes, personal scratch projects, test utilities, that sort of thing). We’d either want no enforced process (particularly for personal projects and the like), or a much more relaxed process.

    Is it possible to set up a single project as you describe, but with more granular control over things like checkin policies? We’re using TFS 2010 currently but we have been eyeing TFS 2012 as a potential upgrade.
    I suppose it would be possible to have a checkin policy check an item’s path against a filter, or something…

    • You can create a proxy policy that does what you want fairly easily. I would however suggest that Check-in Policies should not be used for enforcement but that is another conversation….

      Out of interest… which policies do you have enabled?

      • …I’d be very interested to hear why checkin policies shouldn’t be used, and what the alternative is. Perhaps that’s a good subject for a post. :). We know there are a few issues with them, but haven’t found another way to nudge developers towards the right process. (For example, forgetting to set the Area is a common error).

        Thanks for the proxy policy tip. Is there any specific documentation for that?
        We have the comments policy, the workitem policy, a custom policy that validates that the workitem you associate is in the right state and has the area and iteration set, and a custom policy that checks whether you have run a particular analysis tool.

  • Alain Rodriguez

    This is a fantastic article.
    I do have a question. It is possible to setup one Sharepoint site per Product, just like the one Sharepoint site per Team Project?

    • Indeed it is 🙂

      If you create a sub-site, with the name of teh product, on the site that is linked to the Team Project and enable the TFS features you are good to go…

  • JWS_Thotz

    I have found the discussion around Area and Iteration Security to be more than light. When we set security at a root level, it seems that visibility and access inherit downward… but it seems that trying to set security at a subnode level forces you then to explicity manage every node underneath. Wanting not to explicity manage dozens of even hundred of individual nodes (we have complex enough systems that many iterations and areas exist) how do we proceed? The only option I have seen is manually addressing subnodes or running code every time to pick up subnodes – both demanding admin level rights. Right now on our TFS 2010 implementation… in Test Manager, users with full node rghts (but not an admin) on areas and iterations cannot create test plans in that same node. Security has not been properly explained in my mind – the MSDN docs fail to detail anything useful and I have seen Visual Studio articles that are just wrong. Knowing how 2010 security around areas and iterations really works and what – if anything – has changed in the model would be a huge help.

    • John,

      The first thing that I would recommend is to move to at least 2012.3.

      Next, I am not sure of the issues that you mention. The permission work just like ACL’s on folder and by default they inherit all the way down. If you set AreasMyTP as having no read permission and then set read on AreasMyTPProduct1 then everything under Product1 get the same inherited permissions. However Product2 would not get any permissions.


      • JWS_Thotz

        2012 is on the runway – but we have about 11 collections, over 100 team projects, and too many things in flight until the smoke clear. Its an enteprise implementation and the decisions for moving are pretty much done about 3 levels above me. For now – the move is not a priority and is probably months away.
        I would recommend trying what I suggested. There are articles online saying that it does inherit and some that you are stuck explicitly managing each node. The security does not inherit if it is set anywhere but the root – based on observations so far. Its easily observable from Team Explorer or Sidekicks. So until someone can publish a detailed explanation of what we are observing – my position is that no one is bothering to look at this; but we depend on a manageable solution to the problem. We generate thousands of test cases and hundreds of plans – we have chosen a large project with many subprojects approach and security is not working. Having to do it over because MS fails to understand and document its product – that is not something we want to absorb; we have product to work on and better things to do than spend time experimenting to see how TFS works in reality. The Microsoft Documentation is profoundly incomplete – and beliefs do not trump reality. Inheritance is not happening. The restrictions may not alter the ability to change things in common work items – but the inability to create any test plans now is a huge issue.

  • Ricky Jenkins

    Hi Martin, I am presently moving multiple team projects all with team sites associated with them. Is there a recommendation to get all of them under a single team site as well?

    • You are going to have to use the TFS Integration Tools to do that.

      Note: That will not be a pleasant experience 🙁

      • John Ludlow

        Particularly if you have a large code base. We tried it, and it died because it ran out of memory. I think it’s trying to store all its data in memory, and it’s a 32-bit process, so it can process a certain amount of data and then it goes pop!

        • Its when you have large individual check-ins. It has to do each check-in in its entity as it cant split them up so if you have 50k things in a single check-in you are likely to have a problem. I have run into this issue with 50k+ items in a single check-in.

          • John Ludlow

            Ah, that’s a useful tidbit to know! This is probably down to our merges between dev branches and the main branch, or between release branches for different versions of the product. They’re our largest changesets and probably exceed 50k items by some margin.


  • Pingback: Why You Should Use a Single TFS Team Project — Imaginet Blog()

  • Ramesh

    hi Martin, I use CMMI model in tfs 2010 and I have one Team Project for WorkTracking (Work Items, Areas per application, teams, One common iteration/release cycle path followed across the organization) , and individual team projects for each Application. I modified the work item Queries of each application team project to list the Work items/area from the WorkTracking team project. The Individual projects gives the app team flexibility to manage code and permissions seperately. I plan to use a similar approach in my new TFS 2013 implemenation. Can you suggest if this is a good model. also I want to use the Team concept of TFS 2013 and am wondering how to do it with the above model. please advice.

    • Teams do not cross the Team Project boundary. As long as everyone opens the one team project that contains the work items it will work OK, but you should consider folding everything together…

      • Ramesh

        Our users are used to that existing model and hence I want to see if its possible to implement a similar solution. Is there a way to link the individual TFS or Windows groups of Application team Projects to the “Teams” of the WorkTracking team project ? that way the “Teams” of WorkTracking project are indirectly connected to the TFS or Windows group.

        • A Team is just a security group with meta data so you can easily add windows groups.

        • If you have multiple team projects and queries cross the Team Project boundary you are very far off the happy path for the product and will not get the support you want. I would strongly recommend changing the way the users are used to working 🙂

          • Ramesh

            Agreed. I will go ahead and persuade the user groups with the One Team Project Approach. My other question is – all of our user groups use one release cycle using waterfall CMMI model and hence one team project with CMMI process template will suffice. But we are also planning to start Agile process model for few of the user groups early next year. I am trying to understand how the source code can be shared from the CMMI team project with the new Agile Team project in future where both Agile and CMMI are going to be followed by the same user groups. Any advice ?

          • That is a little more challenging…

            1) one option would be to have two Team Projects, one for each process… I would recommend having each one in a different Collection as well (one team project per collection) but that is a different question.

            2) The second is to convert the existing project over to a modified Scrum template that puts bugs on the backlog but calls PBI Requirement. You can then keep Change Request, Risk and change Issue to Impediment to complete the picture. Teams can then do Agile or Waterfall within the single Team Project but they have an ‘agile’ template that gives them ‘agile’ compatability.

            As the Scrum template is the only template that natively has bugs on the backlog and that it has no enshrined wall between code and test, it is the only one that I consider to be based on lean-agile principals. I ALWAYS use that template as the base and may import features from the ‘Agile for MSF’ or ‘CMMI for MSF’ templates as the need arises.

  • woz17

    Thanks for the great article, I have made extensive use of it during our evaluation of TSF2012. I believe I have a good grasp of Teams/Areas/Iterations. However I am still missing one thing. How can I restrict users from simply selecting another team via the Left hand top menu in the Web Client (see attached). Therefore users assigned to Team X can simply select the top level Product Management Team and see all Themes/Stories for all teams, current and future. It does not seem to matter that the user is assigned to Team X, they can still select any other team in the web client (or I am missing something).
    Any thoughts would be appreciated

    • DW5

      Woz17 – any luck with your issue? I have the same question and problem…

      • OK, so you can’t, but there is another way… If you click the little drop-down on the Area Path you can secure both the View and Edit of Work items contained within it. So while Team A can select Team B, it does not need to have Write or even Read access to the Work Items it contains.

        Does that make sense?
        On the other side of that, the agile side, you should have a teams backlog visible to all… do you put a cover over your wall board? or is it visible and editable by all of the teams. You trust that they will not touch it, but they can…


    Since this article, GIT-TF has been introduced. For those that already had projects in TFVC and have other projects that have to use a GIT repository, is this method still recommended? Which would mean moving things from the TF repository over to GIT-TF.

    • It is still relevant if you are moving everything to Git. Just exchange permissioned TFVC folders for Git repositories.

      However if you are already in a single TFVC team project then you should wait for the TFS Product Team to implement the ability to add Git Repos to an existing TFVC, which i believe is imminent.

      • BANNER

        We are not currently in a single team project. Seems either way we will lose information by going to a single team project.

        I did see a future update – TFS 2015 Update 3 or 4 – may include support for mixing TFVC and GIT.


    Also, how are backups handled when you use GIT-TF?

    • Not sure i understand the question! Both Git and TFVC are backed up using the built in backup tools and all data is in SQL databases. Git-TF is only a tool for pushing between the two.

      In most cases you use Git-TF to migrate from TFVC to Git and never look back.

      • BANNER

        Sorry, disregard that. I just looked at why that was even in my mind and realized it was talking about a different database being backed up by using GIT was wrong.

  • Johnny Boldt

    Does a single team project still make sense with TFS2015, or has new functionality made it unnecessary? We are currently on TFS 2013 with multiple projects and it is clear that one project with multiple areas will solve a lot of our issues in terms of visibility and reporting. But we are also planning on upgrading to TFS2015, so I was curious if it still makes sense to consolidate to one project.

    • Its still relevant. Although you can now ( on VSTS) change a work item type, and move one between projects, there is still no ability to report or create backlogs across projects. I still advocate for One Team Project to Rule them All…

      • Johnny Boldt

        Thanks for the quick reply! I asked this at but never heard back. I will be sure to add a link to here!

      • Nathan Brown

        Visual Studio Online can now do queries across projects.

        I’m having difficulty with the single team project and an area for each team/application each with their own git repositories. When you go to the “Code” tab, it always goes to the last git repository accessed, not the one that you want associated with that specific team/area.

        • You have been able to query across projects, but that does not allow you to create backlogs across projects. If you have one team, or one PO, or teams working across multiple backlogs and you want to order and prioritise together then you have no choice. I prefer individual projects with VSTS now, but I cant as I need a unified and ordered backlog.

  • Pingback: Visual Studio Team Services and Matrix Organizations – Agile – ALM – DevOps Blog()