Skip to content

Latest commit

 

History

History
91 lines (74 loc) · 4.47 KB

workflow-branching.md

File metadata and controls

91 lines (74 loc) · 4.47 KB
Raw

Git Tagging/Branching Mechanisms

During regular development, developers will routinely create temporary branches for code reviews. These branches are not the focus of this document, as they are generally short lived (as short as a few minutes, or as long as it takes for a developer to complete his work).

When working on branch “master” (equivalent of the improvement branch on Team Foundation Server, our prior source code management system):

  1. We will normally have one development stream: Branch “master”. This is the equivalent of the “improvement” branch in TFS, and represents our “latest/greatest” code. Most developers work on this branch, or a sub-branch of this branch, the majority of the time.

  2. When we need a branch to stabilize a release, we will create a branch on the fly for that purpose with a meaningful name, and cherry-pick or hand-merge changes as necessary to make the branch stable. Once stable, a tag will be created with a meaningful tag for the release and then the branch can be deleted. As an example, we may create a branch named "TP5-stabilize". Once the branch is stable and we ship code from it, we can create a tag named "2016-TP5" and then remove the branch when it is no longer actively used for development.

In addition, we’ll have two categories of other branches in our repositories:

  1. Release branches, and

  2. Long-lived development branches. These would be for a long-lived development effort (something that several people may work on, or something that may not be checked in for some period of time). Eventually, as this work gets merged to the “master” branch and/or to a “release” branch, the long-lived development branch will be deleted.

To manage a long-lived development branch, developers should create temporary branches off of it. This allows code reviews in manageable chunks while still allowing the long-lived development branch to be re-based if needed for ease in future merging.

###Release Branches

In addition to the above, we can have any number of “release” branches. Examples of such release branches might be “2016-URNext”. This would be intended as a Update Rollup development branch for the 2016 release of Operations Manager, for example.

Note that, in ‘git’, there is a difference for a branch and a tag. A branch is something long-lived, intended for further checkins, while a tag is a one-time snapshot of versions of files.

To further illustrate the difference: A tag represents a version of a particular branch at a moment in time. A branch represents a separate thread of development that may run concurrently with other development efforts on the same code base. Changes to a branch may eventually be merged back into another branch to unify them.

Usually you'll tag a particular version so that you can recreate it (i.e. "v1.1.0-2"). A branch is more of a strategy to provide on-going updates on a particular version of the code while continuing to do development on it.

It is likely that 2016-TP5 (Technical Preview 5) will be a tag off of the master branch. However, if the master branch is not stable at the time 2016-TP5 will be produced, we can create a stabilization branch (as documented above) that will be used temporarily to create a stable build.

Meanwhile, as we’re working on “2016-URNext” (a branch), when we decide to actually ship a UR out of it, we can tag that to be “2016-UR1” (for the first UR), leaving the “2016-URNext” branch for further work. Each time we ship code for a supported release, we create a tag for that release (regardless if the release is off of 2016-URNext or off of some temporarary stabilization branch).

Tags can be created either on the master build project (bld-scxcore or bld-omsagent), called a super-project, or on the individual repositories involved. Because we need to track all dependencies on a release, we will create a tag on the super-project (which will automatically capture all dependencies). Note that we may also choose to tag a primary project (like OMS-Agent) as well if we want to use GitHub as a distribution vehicle for the release.

Finally: Shell bundles, when generated by a project, should support the “--source-references” qualifier. This qualifier will dump all relevant git commit hashes (via qualifier “--source-references”) that went into producing that shell bundle. This makes it very easy to see exactly what source code the shell bundle represents.