title: Team Foundation Server Source Control Structure
body: <p>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 <a href="http://www.codeplex.com/BranchingGuidance" rel="noreferrer">Microsoft Team Foundation Server Branching Guidance</a> documentation available on CodePlex.</p>
  
  <p>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.</p>
  
  <p>First, I will outline and describe the decisions and usage.</p>
  
  <pre><code>$/                                                
      {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}/
  </code></pre>
  
  <p>The general logic is that a Team Project can contain either a single logical project (where there would be no <code>{Subproject}</code> entry) or multiple related projects in the form of a product or tool suite.  The three major containers are called <code>Development</code>, <code>Integration</code>, and <code>Production</code>.</p>
  
  <p>Within the <code>Development</code> container's Trunk, there are provisions for both the projects which make up the product in the <code>Source</code> folder, with corresponding unit tests available in the <code>Tests</code> folder.  A majority of minor development would occur in the trunk, with branching available through the <code>Trunk</code> folder's sibling <code>Branches</code> folder, which acts as a branching container.  One or more solution files would live within the <code>Trunk</code>, allowing for branches at that level to capture the solution, source, and unit tests.</p>
  
  <p>The <code>Integration</code> container, often called "main" in non-TFS implementation, is solely used to integrate Changesets from <code>Development</code> to create a stable and testable build.  It is initially created as a branch from the <code>Development</code> 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.</p>
  
  <p><code>Production</code> is used to produce pre-production and production quality builds.  It is initially created as a branch from the <code>Integration</code> container once a stable build has been recommended for release.  Within the <code>Releases</code> folder, a "branch by release" structure is followed, providing snapshotting and isolation in a single place.  (For example, when <code>Release 1.1</code> is ready for a pre-production build, the stable <code>Integration</code> container is branched into a new <code>Release 1.1</code> folder in the <code>Production/Releases</code> structure.  Subsequent RCs and RTWs/RTMs are promoted into this folder, as well.)  A branching structure is also present, as seen in the <code>Branches</code> 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 <code>Release 1.1.1</code>.  The Changeset would be reverse integrated to the <code>Development</code> container's <code>Trunk</code> upon acceptance.</p>
  
  <p>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:</p>
  
  <p><strong>Team Build</strong> - The <code>Development</code> and <code>Integration</code> containers will initially start out as being nightly builds, eventually moving to Continuous Integration (CI).  The Production container will be manually built.</p>
  
  <ul>
  <li><p><del>Where should the build definitions live?</del> <strong>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).</strong></p></li>
  <li><p>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.</p></li>
  </ul>
  
  <p><strong>Documentation Generation</strong> - We use Sandcastle to generate documentation.  Specifically, we also use <a href="http://www.codeplex.com/SHFB" rel="noreferrer">Sandcastle Help File Builder</a> to manage the output.  This produces a project file in a format specific to SFHB.</p>
  
  <ul>
  <li><p>Should generated documentation be stored in the source control structure?</p></li>
  <li><p>Should documentation be generated for each container, or does it only posses value for pre-production and production quality builds?</p></li>
  <li><p>To preserve fast local build times, should documentation creation be owned by a build definition?</p></li>
  <li><p><del>Where should the SHFB-specific files live?  My initial inkling is to put it as a peer to the <code>Source</code> and <code>Tests</code> folders.</del> <strong><em>I agree with the recommondations that it be a peer to <code>Source</code> and <code>Tests</code>.  Diagram changed to reflect this change.</em></strong></p></li>
  </ul>
  
  <p><strong>Third Party Binaries</strong></p>
  
  <ul>
  <li><p>Should binaries (controls, libraries, etc.) be stored in source control?</p></li>
  <li><p>If so, should it be it's own Team Project?</p></li>
  </ul>
  
  <p><strong>General Documentation</strong> - 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.</p>
  
  <hr>
  
  <p>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.</p>
  
  <p><strong>Edits:</strong></p>
  
  <ul>
  <li><p><strong>Clarification.  <code>Source</code> and <code>Tests</code> folders do live under the <code>Integration</code> container, as well.</strong></p></li>
  <li><p><strong>Both Micah and Josh brought up great points regarding third party binaries.  Question added regarding the issue.</strong></p></li>
  <li><p><strong>Documentation generation can be slow.  Question added regarding whether documentation creation should be owned by a specific Team Build Type.</strong></p></li>
  <li><p><strong>Added resolution related to non-generated documentation, such as requirements, design documents, test plans, etc.</strong></p></li>
  <li><p><strong>Added resolution related to TeamBuildTypes folder for build defintions.</strong></p></li>
  <li><p><strong>Based upon various feedback, moved the TeamBuildTypes folder to the trunk / branch levels.</strong></p></li>
  </ul>