VS ALM Rangers Branching Guidance–Shared Code and Dependency Management

  • Article

As we begin planning the next release of the branching guidance, a top priority is to address how to manage shared code dependencies (the Dependency Repository / Shared Code issue). The newly release Build Customization Guide (now available for download from Codeplex) begins to address this issue, primarily from a build perspective. For the Branching guidance, I would like to go beyond that offered in the Build Customization Guide. I would like to provide more details for each the recommended scenarios including screen shots from Visual Studio Source Code Explorer to show the proposed folder /  branch structure for each scenario.

For the Branching guidance, I am thinking of using Enterprise Library 4.1 AND Enterprise Library 5.0 to show the following:

  • How to create / structure a Dependency Repository with different versions of assemblies to use with binary references in the Dependent Projects
  • How to create / structure a Dependency Repository with different versions of source code to use with project references in the Dependent Projects

The four scenarios described in the Build Customization Guide are

  1. A centralized, dedicated Team Project (for example $/Dependencies). This is a good approach for sharing dependencies across multiple team projects.
  2. A dependencies folder in the root of a product’s or project’s Team Project, for example, $/Contoso/Dependencies. This is a good approach for centralizing dependencies and promoting re-use.it will also suit the needs of most teams.
  3. A dependencies folder under each dependent product or project, for example, $/Contoso/ProjectX/Dependencies).
  4. A dependencies folder under a branch in the dependent project’s Team Project, for example,$/Contoso/ProjectX/Main/Dependencies).

I would like to go beyond the guidance in the Build Customization Guide, by providing guidance to help people choose from these four options.  For example, what are the benefits and disadvantages of each approach. Why would I choose one over the other?

In addition I want to include, in the Branching guide, examples for each of these four options (or which ever options we choose to recommend) for creating references (one example for binary reference, one example for project reference).

Questions we need to answer:

  • Do we create references from the Dependent Project directly into the Dependency Repository?
  • Do we copy DLLs from the repository into a folder in the Dependent Project?
  • Do we branch from the Repository into the Dependent Projects?
  • If we branch, where is this target branch located in the Dependent Project?
  • Is the target branch located outside of the branching structure of the Dependent Project or is it (somehow) nested within the branching structure of the Dependent Project?
  • What are the issues associated with each approach?
  • How do I deal with not being able to create nested branches in VS 2010?
  • Do I allow only one-way merging (from the Repository to the Dependent projects)?
  • Do I allow bi-directional merging so that the Dependent Project can actually change the source of the shared code and merge these changes  back to the repository?
  • If I don’t branch from the Repository what are my other options (copy? Reference directly?).
  • If the dependency repository is maintained outside the branching structure of the dependent project what other issues arise (relative folder depth for relative references).
  • When do I create project references to shared code vs. binary references. What are the pros and cons. Any gotchas?

The four scenarios described above are from the Dependency Management section of the Build Customization Guide. As much as possible, we should ensure that the guidance for sharing code and managing dependencies is consistent between the Branching guide and the Build Customization guide. This does not necessarily mean we have to incorporate all four of the Build guidance scenarios into the Branching guide. We also should not necessarily be confined to these four scenarios.

Some dependency management scenarios I envision discussing in the Branching guide include:

  • Create a *centralized* dependency repository, in its own Team Project, and show how other consumers (Dependent Team Projects) would create references to either DLLs (binaries) or Source Code (Project References) across Team Project boundaries. What are some of the issues (security is one).
  • Create a dependency repository *within* a Team Project shared by other consumers within the same Team Project. Have the consumers establish references from projects *within* a branch to either DLLs or Source Code in the repository *outside* the branch. What are some of the issues, such as how to avoid breaking relative references when branching and or building code on a build server.
  • Create a dependency repository in a folder beneath a branch. This simplifies workspace mapping issues perhaps and would be one way to address how to avoid breaking relative references.

For each of the scenarios we settle on, we should talk about the considerations for choosing one over another. Some of the considerations I can think of include:

  • The need to support multiple versions of the shared dependencies (DLLs or Source Code) (producers)
  • Frequent vs. infrequent updating of the dependencies (producers)
  • Number of consumers (dependent projects)
  • Team Project Organization (is the repository in its own Team Project – perhaps shared by multiple products, product groups, or teams, or is the repository within a Team Project – perhaps where the same team owns the shared code and the dependent projects, products, or product groups)
  • Workspace mapping considerations
  • When to use Project References vs. Binary References
  • How to propagate changes to the shared code to all of the consumers (Branching from producer to consumer, vs. Copying from producer to consumer, vs Relative References from consumer to producer across branch and / or Team Project boundaries)