Branching and Releases - ARA-Trans/iAM GitHub Wiki

Core branches

  • master --- Permanent
    • For the next release.
    • Tags: none
  • release/vX.Y --- Permanent when created
    • Branched from master.
    • For released product version X.Y.
    • Tags: vX.Y.Z, vX.Y.Z-preview.N
  • release/vX.Y.Z-hotfix.# --- Permanent if created
    • Branched from tag vX.Y.Z on branch release/vX.Y.
      • Instigated by issue #.
    • For urgent re-release of "non-universal" changes for product version X.Y.Z.
      • Non-universal here means "not applicable to all users".
    • Tags: vX.Y.Z-hotfix.#.N
  • vnext/# --- Transient
    • Branched from and merges to master.
    • Resolves issue # for the next release.
  • vX.Y/# --- Transient
    • Branched from and merges to release/v*.
    • Resolves issue # for released product version X.Y.
  • vX.Y.Z/# --- Transient
    • Branched from and merges to release/vX.Y.Z-hotfix.##.
    • Resolves issue # for urgent re-releases of product version X.Y.Z.

Version sub-numbering for hotfixes and previews

The identifier N in vX.Y.Z-hotfix.#.N and vX.Y.Z-preview.N tags always starts from one (1).

When the relevant branches are created, before the first tag exists, any hard-coded version number in the app assets can be set to zero (0). Otherwise the version number in the app assets should be updated to the tag value before the tag is applied.

Supplemental branches

  • support/#
    • Branched from anything.
    • For changes that
      1. can't be included in a regular or hotfix release but
      2. are still required in order to support a customer.
    • Resolves work item #.
  • user/ABC
    • Branched from anything.
    • For personal development by user ABC.
  • experimental/xyz
    • Branched from anything.
    • For experimentation related to topic xyz.
  • archive/xyz
    • Branched from any prefix/xyz.
    • To indicate inactive branches whose histories are not otherwise preserved.

Tags

We always tag any commit from which we have built and distributed a binary executable.

This includes both public releases and any internal releases.

Tag format is a semver label, with some specific conventions and constraints. By way of some examples:

  • v2.5.1
  • v2.5.1-hotfix.1234.1
  • v2.6.0-preview.2

An attempt at a pseudo-regex for this format: vX.Y.Z(-(hotfix.#|preview).N)?

Note that this format is strict. No other label components or literals are allowed without team consultation and good justification.

Prefixes and suffixes for branch names

Descriptive suffixes are always allowed for branch names. Here's an example of an acceptable suffixed branch name:

vnext/1234-prevent-foobar-invalidation

Categorizing prefixes are not recommended but may be approved for use by the team.

"Square of Success"

To guarantee a successful PR merge from a topic branch (e.g. vnext/# or v*/#) back to its source branch (e.g. master or release/v*), do the following local git operations:

  1. Checkout the target branch.
  2. Pull.
  3. Checkout the topic branch.
  4. Merge from the target to the topic.
  5. If there are any conflicts, resolve them and commit the changes.
  6. Push.