Guidance for Structuring Team Projects

- Doug Neumann - Microsoft Corporation

Introduction

One of the most important considerations when looking to deploy Team Foundation Server within your organization is how you will employ the “Team Project” concept. It can be very tempting to jump in and immediately start creating Team Projects to satisfy every whim of the users in your organization. However, restructuring existing team projects is difficult to accomplish, so establishing a strategy for using team projects up front is very important. Careful forethought now can save you much pain down the road.
This whitepaper provides details on the components of a team project and discusses how those components may impact your decision about structuring your team projects. It also lays out a set of common strategies for employing team projects. Understanding this base of knowledge should empower you to make the best decision on how your organization will use team projects with Team Foundation Server (TFS).

What is a Team Project?

A TFS Team Project is a collection of artifacts that is used by a team of individuals to perform and track a related set of work. All artifacts stored in TFS belong to one and only one Team Project, and you cannot begin working in TFS until you have created at least one Team Project. Team Projects are created by a TFS administrator using the Team Project Creation Wizard.
The initial settings of a team project are governed by a process template. This template configures a new team project in accordance with a specific software development methodology that the people working on the team project will follow. TFS ships with support for two software development methodologies, but additional process templates can be added to the system, and all process templates can be extensively customized to fit the needs of your organization.

Components of a Team Project

Understanding artifacts being leveraged within your organization, the need for cross-organizational sharing of artifacts, and the available strategies for sharing TFS artifacts across team projects will lead you to the best decision about how to structure your team projects. The following table outlines the list of artifacts managed by TFS and the capabilities for sharing those artifacts between team projects.

Artifacts & Settings	Description	Considerations for Structuring Team Projects
Source Code	TFS manages your source code in its version control system. Each team project creates a top-level folder in the version control folder hierarchy and no other files or folders can be created in the root of the version control folder hierarchy. Every item created underneath a team project folder is “owned” by that team project.	Source code can be shared between team projects in various ways, including branching source from one team project into another and mapping source from another team into your workspace. TFS does not support the Visual SourceSafe style of file sharing where a single file can be manifested in multiple locations within the version control repository.
Work Items	Instances of work item types allow you to define and track the work being performed within your organization. When a new team project is established, an initial set of work items is created for you as defined in the process template used for that team project.	A work item belongs to the team project in which it was created and cannot be moved to another team project. Work items can, however, be copied to another team project, at which time the fields in the newly created work item are pre-populated with the value of the corresponding fields in the source work item. Currently, there is no mechanism for bulk-copying work items between team projects in TFS.
Work Item Types	The fields, form, and workflow of a TFS work item is governed by an XML definition known as the work item type. Work item types are defined in the process template used to create a team project and can be customized as necessary after the team project is created.	If you plan to track work across multiple projects using the reporting mechanisms in TFS, you’ll need to ensure sufficient consistency in the work items defined in those team projects. They do not need to be identical, but they need to share the set of fields being leveraged for these reports.
Work Item Queries	TFS persists a set of work item queries that provide a mechanism for team members to share views of the team’s work.	There is no way to structure work item queries in TFS beyond declaring them as Team queries or “My” queries. Large team projects with a lot of queries can make it difficult to find the queries users are interested in. This may encourage a more granular team project structure to minimize the number of queries that a single team project contains.
Team Build Types	Automated build definitions in TFS allow you to execute a build of your application(s) in a reproducible manner. Each team project has a collection of build “types” associated with it. Build types are persisted as files in the version control system.	By default, a single build type can only compile source from the team project in which it exists, however it is possible to modify the build definition to enlist source from outside of the team project.
Reports	Each team project creates a reporting site in SQL Reporting Services and a collection of reports that report on the progress and activity within that Team Project.	The data for all team projects on a given TFS exists in the same data warehouse, so it is possible to create custom reports that span multiple team projects. However, the reports included with TFS provide only a single-project view.
Team Portal	Each team project creates a Windows SharePoint Services portal to be used for collaborating within that team.	Team projects cannot share the same team portal, however if teams wish to collaborate with each other using the same portal, they can easily agree to use the portal created for one of the teams. SharePoint portals maintain their own set of security permissions if it’s necessary to govern portal permissions differently than other TFS permissions.
Process Guidance	Each team project portal contains a collection of web pages to provide guidance about how to follow the software development process being utilized.	Only one set of guidance exists for a given team project, however this typically does not influence the decision on how to structure team projects.
Area and Iteration Classifications	Area and iteration classifications provide a mechanism for you to decompose your application functionality and project timeline respectively. These classifications can then be applied to work items and other artifacts to make it easier to find the artifacts that are appropriate for a given area of the application or iteration of the timeline.	Area and iteration classifications are completely contained within the team project in which they are defined and cannot be shared between team projects. It is possible to manually replicate the area and iteration classifications between team projects if necessary. Also, the initial area and iteration hierarchy can be defined in the process template if standardization across team projects is desired.
Security Groups	TFS provides a mechanism for aggregating users into security groups for the purpose of controlling access to the system. Groups are defined at the server scope as well as the team project scope. TFS security groups can aggregate Windows user accounts, Windows groups and other TFS groups.	The security groups mechanism in TFS is quite flexible and is unlikely to influence your team project structure.
Check-in Policies	Checkin policies provide a mechanism for validating user changes to source code before they are committed to the system. Every team project defines a set of checkin policies that will apply to checkins in that team project.	Checkin policies cannot span multiple team projects, however policy definitions can be manually replicated to other team projects. Furthermore, checkin policies cannot be scoped to a subsection of the team project source, making it sometimes difficult to work with checkin policies when a team project contains a multitude of subteams. The Team Foundation Power Tools contain a checkin policy that can be used to scope other checkin policies to specific areas of the source tree.
Exclusive Check-out	A team project can specify whether files in version control will be locked when checked out or remain available for additional parallel checkouts.	Because the exclusive checkout setting is scoped to the entire team project, sub-teams wishing to work differently will need to come to an agreement about whether or not they’ll enable this feature.

Team Project Scalability

For some customers, the most important consideration in structuring team projects is the number of team projects that can co-exist on a TFS without significantly hindering server performance. Scalability of team projects is limited by the complexity of the work item types defined on the server. The work item types included in MSF for Agile Software Development have been shown to scale to support 500 team projects on a server. Similar testing with the work items in MSF for CMMI Process Improvement have been shown to support 250 team projects on a server. For more information about team project scalability, go here.

Strategies for Employing Team Projects

There is no one right way to structure your team projects, and your needs may change as your software development process evolves. That being said, there are 3 common strategies used to structure team projects. You may find that one of these strategies fills the needs of your organization or that you’ll choose a combination of these strategies as appropriate for the nature of your work.

Strategy 1: Team Project Per Application

The most common strategy for creating team projects is to create one for each application under development. This strategy can support both large and small applications, as well as multiple releases of applications being developed in parallel. Various releases of the application are manifested in the version control system as source branches, and in other parts of TFS as different nodes in the iteration classification hierarchy. If appropriate, documentation for each release that is stored in the SharePoint portal can be managed in different document libraries.
Following this strategy greatly simplifies the process of moving requirements, features, scenarios, and bugs between releases. When an item needs to be pushed out or brought it, it is signified by simply changing the iteration path to reflect the new target release.
The biggest drawback to this strategy is that the software development process for all releases of the application are tightly bound. For example, two releases of an application being developed in parallel would need to use the same work item types, the same checkin policies, and follow the same process guidance.
Another potential drawback is that you may need to customize the reports included with your process template to get an appropriate view of what is happening in a given release. Most reports included with the common process templates provide a team-project-wide view of what is happening; to get a view that is focused on a single release, you may need to add additional filtering for that release.
Over the course of multiple releases, you may find that your team project for a given application has developed a lot of “baggage.” This could include old work items that are no longer needed, old specs on the portal that should have been discarded, or old data in the data warehouse that could cloud your view of team progress. Additionally, you may decide at some point that you’d like to change your software development methodology and desire to retool your team project to support that methodology. At that time, you may find it is appropriate to create a new team project for this application, starting clean with a new process template, a new set of work items and a new project portal. You can then branch source from the previous team project to the new one, and copy work items as appropriate to the new team project.
Finally, an organization managing hundreds of small applications may eventually reach the scalability limits of TFS. For more information, see the previous subject on Team Project Scalability.

Strategy 2: Team Project Per Release

In the “Team Project Per Release” strategy, every major application release starts a new team project. This strategy works well for very large teams who are often working on long-term projects. For these teams, a major release is an opportunity to start clean with a new team project that doesn’t carry forward any baggage from the previous release. By starting with a new team project they can also select a different process template that supports a different development methodology than they had previously followed. They can also selectively move forward artifacts from the previous release to eliminate some of the baggage frequently left over from a multi-year effort. The team project from the current release can continue to be leveraged for maintenance activities on the release, potentially with a different team that is responsible for sustaining engineering.
The primary disadvantage with this strategy lies in the difficulty of moving data forward from one team project to the next. It is relatively easy to move source code between team projects, typically by branching the source into the new team project. Moving work items forward, however, is more difficult. TFS provides the ability to copy a work item from one team project to another, but that only works on one work item at a time. To copy a set of work items between team projects, you would need to write your own custom utility with the TFS object model.
Server scalability can also be a concern with this model, however usually organizations engaged in these projects find they are managing a few large efforts rather than many small efforts. The server scalability concerns related to structuring your team projects only come into play when managing hundreds of team projects on a Team Foundation Server. For specific scalability numbers, see the previous subject on Team Project Scalability.

Strategy 3: Team Project Per Team

For a few customers, the best way to structure team projects is to align them with the team boundaries in their organization. This strategy closely aligns a team with the workflows defined in TFS work item types and provides a unit of reporting that spans the entire team. For customers looking to centrally control and monitor the activities of software development teams, this may be the best approach.
This strategy can be a necessity when encountering the team project scalability limitations discussed previously. Organizations that manage several hundred applications may find that they need to group applications together under a fewer number of team projects. An appropriate criteria for grouping these applications is frequently to cluster together applications developed by the same team.
The primary disadvantage of this approach is that it precludes specialization of the software development process for a particular application or release. If one application in an organization needs a new field on a work item type, all applications will get that new field. Additionally, reports that show timeline details of the team project lose their value if the applications managed in the team project are not working toward the same timeline.

Providing Substructure Within a Team Project

Regardless of the strategy you choose, you will need to provide some level of substructure to your team project. If you select the team project per application model, you may need to create substructure for each release. If you are working on a very large application and select the team project per release model, you may need to establish substructure for subcomponents of the application. And if you select the team project per team model, you will probably need to establish substructure for the applications that the team works on.
The mechanisms for providing substructure depend on the type of artifact being managed. The following table discusses the substructure mechanisms for the artifacts and settings discussed previously.

Artifacts & Settings	Substructure Mechanisms
Source Code	The top level structure for source code within a team project is typically a “branch.” Branches in TFS appear as copies of the files and folders they are branched from. Frequently, the first thing you’ll do in source control for a new team project is to create a new folder with a name like “main” that constitutes the main branch for your source. Future branches would likely be made using that folder as the source. Within a branch, structure is typically provided with a folder hierarchy of your choosing. If you find you have a proliferation of branches, it is possible to group related branches underneath a single folder. For example, if you have several branches working in parallel for a given release, you may choose to create a folder for that release and then create your branches underneath that folder. If you’ve already created your branches and wish to reorganize them, you can move the root folder of the branch to the new location with the move operation.
Work Items	Work items are classified according to 2 dimensions: the area path and the iteration path. The area path classification can be used to classify work items for particular components within an application or applications within an application suite. The iteration path can be used to classify work items for a given release or a particular iteration of development within a release.
Work Item Types	There is no way to provide substructure to the list of work item types in a team project, however most team projects limit themselves to a few work item types and substructure is not needed.
Team Build Types	There is no way to provide substructure to the list of team build types in a team project, however it is uncommon to maintain an overwhelmingly long list of team build types. If you are building multiple applications within a given team project, it may be advisable to have several of them build with the same build type.
Reports	SQL Reporting Services allows for reports to be structured into folders. This folder structure is reflected into the Team Explorer in Visual Studio.
Team Portal	Sharepoint provides multiple options for structuring documents stored in the team portal. At the top level, multiple document libraries can be maintained for managing documents with different purposes (such as audiences). Each document library can maintain a unique metadata schema allowing you to track different information about documents based on the library in which they live. Beneath a document library, an arbitrary depth of folders can be established for further structure. Document libraries and the folder structure underneath them are both reflected in the Team Explorer in Visual Studio. At a higher level, sub-sites can also be created in Sharepoint for providing a customized portal for a subset of team project members. Sub-sites are not reflected into the Team Explorer in Visual Studio.
Process Guidance	The process guidance that exists on the team portal is a set of web pages describing the software development methodology being followed. If a subset of the members of a team project need customized guidance, it can be reflected on the existing process guidance pages, or a new set of pages can be created.
Area and Iteration Classifications	The area and iteration classifications are both hierarchies that can be structured as appropriate to represent the functional and temporal breakdown of your application respectively. As mentioned previously, if you are managing multiple applications in a team project, you’ll likely want the top level of the area hierarchy to reflect the applications being managed. Similarly, if you are representing multiple releases in a team project, you’ll likely want the top level of the iteration hierarchy to reflect the releases.
Security Groups	TFS provides a built-in security group mechanism that allows you to manage group membership in TFS rather than through Active Directory or the operating system. These groups can contain any arbitrary set of windows users, windows groups, or other TFS groups. As such, you can subdivide your team as necessary, define the needed groups to represent those subdivisions, and then create additional groups to aggregate those into larger lists of users.
Check-in Policies	Check-in policies are scoped to all source in a team project. This can make it challenging to manage a large source base in a team project because the policies you wish to define for one part of the source tree may not apply for another part of the source tree. The latest release of the Team Foundation Power Tools provides a check-in policy that can be used to scope other check-in policies to a subset of the source tree for a team project.
Exclusive Check-out	Exclusive checkout in version control can be enabled only at the team project level and not on a subsection of the team project source.

Other Common Questions

• How do I structure my team projects for development that is geographically distributed?

Team Foundation Server is built to handle the needs of distributed development teams. The optimized web service protocol and the TFS Proxy server provide an experience for remote users that is comparable to that of users at the site where the server is located. As such, you need not factor geography into your decision about how to structure your team projects.

• Where do I store shared source that is used by multiple team projects?

Team Foundation Server enforces a practice where all top-level items in the version control system are folders for Team Projects. It’s not possible to create a folder in version control that does not fall underneath the root folder of a given Team Project. Consequently, all source belongs to a particular team project.
If you have source that is leveraged by multiple team projects, you have a couple options for handling it. First, if one team project clearly owns the source, it’s probably appropriate to manage that source under that team project. If, however, ownership does not lie with a particular team project, you may wish to create a team project specifically for shared source code. This also provides a convenient place to manage artifacts associated with that shared source such as design documents and bugs.
For the teams consuming the shared source, you have a couple of options. First, those teams can merely map the source from the shared location into their workspaces on the client machine. This creates a configuration that unifies the source from the shared location and their own project on the client-side. Alternatively, the consuming team can branch the source from the shared location into their own team project. This creates a configuration that unifies the source from the shared location and their own project on the server-side. The big difference between these two options is latency in picking up changes to the shared source. In the first case, shared source changes are picked up every time the latest source is retrieved into the workspace. In the second case, shared source changes are picked up as part of a merge process between the branches. This makes the decision to pick up changes in the shared source much more explicit.

• How should I structure my branches?

With the exception of the code sharing model discussed above, branch structure is an orthogonal question to team project structure and one that deserves its own document. A group of engineers from the Visual Studio Team System team recently published a very comprehensive document on the topic. Rather than reproduce that information here, let me refer you to its location.