Product Numbering and Branch Management 2


Introduction

Recently I had to determine a universal product versioning syntax for our products and services.   This was done to ensure a level of consistency between projects and products. Depending on the deployment, currently there has been a wildly different format used between products and services.  

Given the recent adoption of Team Foundation Server 2010 (TFS), and the use of Team Build throughout the product and service range, the new numbering format and branching strategy is designed to support the functionality TFS provides.

Methodology

The cardinal rule of build and release management is: “each build must be unique”.  Without the ability to discern one build from another, a team cannot establish any baselines; nor can issues or defects be reported on, or resolved in, a specific (identifiable) release candidate.

To ensure every build is unique, every product or service release will be identified following a basic numbering format: [Major].[Minor].[Build].[Revision].  In addition to binary numbering (which accompanies files built as part of the build process), the build is identified also by the Build Configuration Name – the name and number form the unique build name within systems such as Team Foundation Server. 

Note that Continuous Integration builds do not require an increment in version number (to avoid a useless increase in the signal-to-noise ratio of build numbers registered in TFS).

image

[Major], [Minor]

The project management team for each project will define the [major] and [minor] numbers for each release in line with project goals and the addition of features and functionality etc. Typically a production release will involve a minor number increment, although should the changes warrant it, a major revision is also likely.

[Build Number]

The [build] number is an atomically increasing number which ensures the uniqueness of each release build and label. Note that CI builds should not increment the product number. Formal builds also create a label within source control, so that the exact source can always be retrieved at any point in the future.

[Revision Number]

The [revision] number should be incremented in the event of a rebuild e.g. due to a build failure or perhaps because a build doesn’t pass smoke testing (and needs to be fixed and rebuilt). The revision number should be reset to zero once the build is accepted.

Note that TFS 2010 uses build labels throughout work items in each Team Project (for example in Bug work items) so that work items can be tied to explicit builds which have been created. These, in turn, can also be linked to automation run executions, changesets, work items and so on.

[The Build Name]

Thus our standard production build will be represented by the following naming convention:

<[Build Configuration Name +  Number(Maj.Min.Build.Rev)]> Example: Widget Release Build [1.0.0.0]

Understanding Source Control

The standard approach to source control management has solutions arrayed in a specific folder structure, often defined as follows:

image

The following definitions are applied:

Root The top level folder in a folder hierarchy
Trunk Represents the main, ongoing development of a solution (or solutions)
Branches Typically represents forks in the source control management, usually branched from the trunk

There are several different valid approaches to source control branching and without going into detail, the most common are:

  • Branch per Release
    • Branch contains a specific product release build
    • Useful for patching production releases
  • Code-Promotion Branches
    • Specific code can be isolated for specific testing
    • Useful for feature isolation development
    • Reduces instances of source file conflicts
  • Branch per Task
    • Rather than branching by feature, code can be isolated according to a specific task, such as vertical architecture changes (e.g. cross cutting concerns)
    • Branch per Component
    • For larger projects, individual components may be branched for independent development and release
  • Branch per Technology
    • Useful when dealing with multiple operating platforms or versions, development can be split in alignment with different technology alignment, or environments

Generally, these approaches stem from a rationale behind change isolation – i.e. reducing the impact of change on the development of a solution’s code base.  To learn more about these branching strategies, refer to the “Further Reading” section below.

Branching and Versioning Scenarios

The following are diagrams and scenarios which outline our approach to product and release versioning under branching scenarios.

Versioning Branches

Since our approach to release management dictates a unique build number per release, and typically an increment in the Major or Minor build number, we may branch source control at any time, continuing the product numbering in parallel.

This means that there may be concurrent builds of a solution with a similar – if not identical – version, differentiated by the build configuration/build definition naming.

When a release candidate is produced – and ultimately put into production – the remaining branches (or trunk, as applicable) are then incremented (typically with the minor version) so that ongoing development now represents the next logical product number.

Persisting Version Numbers

Anytime a Branch is merged back into the Trunk, the version number of the Trunk is persisted, not the branch version. The Branch can be resurrected at any time in the future, by branching from the merge change set.

If a Branch is merged into another Branch, typically the version number of the target Branch is kept.

A Release Versioning Example

Prior to release:

Trunk: 1.2.345.0
Branch A: 1.2.358.0 (branched from 1.2.298.0)
Branch B: 1.2.349.0

After a release from Trunk:

Trunk: 1.3.345.0 [Released as 1.2.346.0]
Branch A: 1.3.358.0 (branched from 1.2.298.0)
Branch B: 1.3.349.0

After a release from Branch A:

Trunk: 1.4.355.0 (branch A merged and released as 1.2.354.0 from the Trunk)
Branch B: 1.4.361.0

Patching

One of the most common scenarios involves patching a released product. Whilst normal development has continued on (on the source control trunk), a branch is created from the released code base, patched, and then the new updated release is deployed to production.

image

A Common Patching/Branching Scenario

Feature Isolation

Below you may observe two different approaches (labelled as options A and B) which can be undertaken to support “feature” branch releases – one scenario avoids a trunk release (option B); both are valid options no matter how many branches exist in parallel – they just require multiple source file merges.

image

In this scenario, the feature branch doesn’t feature the release patch until the final merge to trunk, prior to release

image

In this scenario, the release is made from the branch, then merged into the trunk

In general, it is considered a “best practice” to merge changes to the trunk and release as this avoids potential merges with other branches, and also means rolling changes can be included in other releases. It’s also far less messy in the long run.

Multiple Branch Releases

It is also possible to release and merge concurrent branches, although this carries a fairly large overhead, requiring merging of three (or more) different revisions of files. This has been captured in the following scenario:

image

In this scenario, Branches A and B are merged to the Trunk before being released

Additionally, rather than releasing from the Trunk, it is also possible to merge two branches into a “feature release branch”, prior to merging down to the Trunk. This is captured in the following scenario:

image

This release contains a “feature merge” branch, combining the changes from Branch A and B

Further Reading

Chris Birmele’s Branching and Merging Primer
http://msdn.microsoft.com/en-us/library/aa730834%28VS.80%29.aspx


About Rob Sanders

IT Professional and TOGAF 9 certified architect with nearly two decades of industry experience, 18 years in commercial software development and 11 years in IT consulting. Check out the "About Rob" page for more information.


Leave a comment

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

2 thoughts on “Product Numbering and Branch Management

  • P

    I have to tell you – I was looking for someone who solved the exact mess you describe in this post.
    It’s actually pretty annoying to increment a revision number in the DEV branch, and then merge it into our QA branch (or Release for some people) kick off a manual build there and get a completely different version number. This really confuses everyone and makes it much, much harder than it has to be.

    For example, if you are doing CI in the trunk – you check in 10 times, you end up with version 1.0.0.10
    You merge that into the QA branch, or Release Branch. And then kick off a manual build.
    The build definitions are 1:1 per branch right? So that means you have SomeAppName_1.0.0($REV:.r) or whatever in your build script…which wait for it…cuts a build with version 1.0.0.1

    That my friends, is sub optimal. I wish there was a way to just promote 1.0.0.10 from trunk and call it day. Maybe if there was a way to tag the build in the trunk as ready for testing, and have it branch it, label it, using that same version? I don’t know…but it’s been years with this product and we still can’t bend it to do what we need it to do without writing a ton of custom tasks and code.

    • Rob Post author

      Totally agree. Although I haven’t had time (yet) to experiment with TFS 2012, I’m crossing my fingers and hoping that there have been improvements to versioning and branching (specifically: out-of-the-box solutions, since extending via custom code and custom build definitions is an expensive use of time).

      Problem is, it’s the fourth major revision (2005/2008/2010/2012) and there are still quite a large number of problems for what should constitute a mature SDLC/ALM platform. Each version comes with a fairly messy migration path, but at least now with XAML based build definitions, it seems to be heading in the right direction.