I have been working on standardizing the source control structure for our Team Foundation Server rollout for the new year. I have started by using the Microsoft Team Foundation Server Branching Guidance documentation available on CodePlex.
I was hoping to get some feedback and answers to a few of the specific questions I have about the proposed structure. When it comes to structuring source control in TFS, I have learned that there are so many ‘standards’ to choose from that there is not really a standard.
First, I will outline and describe the decisions and usage.
$/ {Team Project}/ {Subproject}/ Development/ Trunk/ Source/ Tests/ Sandcastle/ TeamBuildTypes/ {Build Name}/ Branches/ {Branch Name}/ Source/ Tests/ Sandcastle/ TeamBuildTypes/ {Build Name}/ Integration/ Source/ Tests/ Sandcastle/ TeamBuildTypes/ {Build Name}/ Production/ Releases/ {Release Version}/ Source/ Tests/ Sandcastle/ TeamBuildTypes/ {Build Name}/ Branches/ {Branch Name}/ Source/ Tests/ Sandcastle/ TeamBuildTypes/ {Build Name}/ The general logic is that a Team Project can contain either a single logical project (where there would be no {Subproject} entry) or multiple related projects in the form of a product or tool suite. The three major containers are called Development, Integration, and Production.
Within the Development container’s Trunk, there are provisions for both the projects which make up the product in the Source folder, with corresponding unit tests available in the Tests folder. A majority of minor development would occur in the trunk, with branching available through the Trunk folder’s sibling Branches folder, which acts as a branching container. One or more solution files would live within the Trunk, allowing for branches at that level to capture the solution, source, and unit tests.
The Integration container, often called ‘main’ in non-TFS implementation, is solely used to integrate Changesets from Development to create a stable and testable build. It is initially created as a branch from the Development container once a testable product has been attained. The builds from this container will be used for our testing environment and load testing environment. We choose to include load testing with testable builds so that we can monitor for changes in performance, being able to rapidly isolate Changesets that may have contributed to any irregularities.
Production is used to produce pre-production and production quality builds. It is initially created as a branch from the Integration container once a stable build has been recommended for release. Within the Releases folder, a ‘branch by release’ structure is followed, providing snapshotting and isolation in a single place. (For example, when Release 1.1 is ready for a pre-production build, the stable Integration container is branched into a new Release 1.1 folder in the Production/Releases structure. Subsequent RCs and RTWs/RTMs are promoted into this folder, as well.) A branching structure is also present, as seen in the Branches container. This allows for ‘hotfixes’, usually a revision marker (Major.Minor.Revision). The branch is created from the current release and merged back into the new revision marker – like Release 1.1.1. The Changeset would be reverse integrated to the Development container’s Trunk upon acceptance.
We feel that this structure is a fair balance between robustness and complexity. But there are a few nagging questions that I can not logically fit into the model. They are:
Team Build – The Development and Integration containers will initially start out as being nightly builds, eventually moving to Continuous Integration (CI). The Production container will be manually built.
-
Where should the build definitions live?Edit – Based upon a couple of responses, the TeamBuildTypes folder has been moved to the trunk and branched to the appropriate containers. This does, however, lead to a new question (follows). -
By having the TeamBuildTypes folder in their appropriate containers, does that mean that all build definitions will be reproduced between the appropriate folders? For example, having a build definition for development quality builds, as well as testable builds, etc. all living in all TeamBuildType folders throughout the structure.
Documentation Generation – We use Sandcastle to generate documentation. Specifically, we also use Sandcastle Help File Builder to manage the output. This produces a project file in a format specific to SFHB.
-
Should generated documentation be stored in the source control structure?
-
Should documentation be generated for each container, or does it only posses value for pre-production and production quality builds?
-
To preserve fast local build times, should documentation creation be owned by a build definition?
-
Where should the SHFB-specific files live? My initial inkling is to put it as a peer to theI agree with the recommondations that it be a peer toSourceandTestsfolders.SourceandTests. Diagram changed to reflect this change.
Third Party Binaries
-
Should binaries (controls, libraries, etc.) be stored in source control?
-
If so, should it be it’s own Team Project?
General Documentation – Non-generated documentation, such as requirements, design documents, test plans, etc. are not going to be reflected by a folder in the source control structure. After some research and discussion with my developers and peers, using the built-in Documents folder in Team Explorer provides more benefit, since it mirrors the structure within the Team Project Portal and some (business) users do not need the additional complexity of learning the source control aspect of TFS.
I will update the structure as I get answers to the questions to provide a clearer picture. I also welcome any other comments related to potential changes. If I have any other questions, I will make sure to modify this post.
Edits:
-
Clarification.
SourceandTestsfolders do live under theIntegrationcontainer, as well. -
Both Micah and Josh brought up great points regarding third party binaries. Question added regarding the issue.
-
Documentation generation can be slow. Question added regarding whether documentation creation should be owned by a specific Team Build Type.
-
Added resolution related to non-generated documentation, such as requirements, design documents, test plans, etc.
-
Added resolution related to TeamBuildTypes folder for build defintions.
-
Based upon various feedback, moved the TeamBuildTypes folder to the trunk / branch levels.
I like your idea of putting the Sandcastle files as a peer to Source and Tests, I would add a documentation folder, that would then contain the sandcastle files, and optionally the actual documentation.
There are definetly differences of opinions and I’m sure I will be downvoted for this (since I have been before). I would put the generated documentation in TFS for a couple of reasons:
One thing I don’t see which I always struggle with is where to third party dependancies, it might be that they belong down under the source so they are with each project although if you wanted to share them accross projects you could add a new top level node.
Edit
For my binaries I usually end up with
$/ThirdParty/Company/Product/Version/Src(optional)
So for example I have
$/ThirdParty/ Microsoft/ EntLib/ 3.1 4.0 ComponentArt/ WebUI/ 2008.1/ Src
I like to add the source, I’ve had to patch CA’s source which I hate to do but when a third party doesn’t fix the bug you have to resort to this.