Semantic Versioning

It is recommended to use semantic version git tags on your repository to label and trigger alpha, beta and production builds. Our SemVer conventions are a subset of the SemVer v2.0.0 spec. A semantic version consists of:

major.minor.patch-team.phase.integration+build

• major is the major version number (integer). A major change for inner source projects is not necessarily a breaking change but rather one that is significant or complex enough to always require cross-team consensus and review.
• minor is the minor version number (integer). A minor change for inner source projects is one that simple or routine enough that is can be released by the local in-team maintainer without cross-team consensus.
• patch is the patch version number (integer). A patch change is a hotfix usually executed under incident conditions.
• team is the team code (string). This can be omitted when there is only a single owning team.
• phase is the release phase (alpha, beta or not present for production).
• integration is an integer that indicates pre-release progression e.g. cumulative number of features, commits or similar.
• build is an integer that indicates build number (omitted if un-used).

By convention the version number is prefixed by a v.

Examples

v2.8.1 is the production 2.8 build after 1 hotfix.

v1.3.0-lds.beta.3 is a beta build for the intended v1.3.0 release. It has been created by the lds team, and has had several bugfixes applied which can be inferred from the .3 integration number suffix.

v3.0.0-alpha.1 is an alpha build for the intended major v3.0.0 release. It has no team element since all tags are created by a single team in this repository. The .1 integration number suffix suggests this is an early build without many features yet.

Why?

Using semantic versioning via git tags…

• Concisely communicates the upgrade risk to your users using a familiar industry standard. For example it is much easier to guess the risk of upgrading v2.1.0 to v2.1.1 than upgrading from version 510 to 511.
• Allows you to release major breaking change without forcing everybody to upgrade at the same time. For example some users can release and adopt v3.0.0 while other users on v2.1.1 can continue to release security fixes until they too can schedule the major v3 upgrade. The alternative of all users adopting the major change at the same time makes scheduling such changes in practice very difficult.
• Using git tags to label versions decouples your CI from your branching model. This allows you to adjust your branching model as your requirements change over time without changing your whole CI pipeline.

Applying the Tags

Creating an annotated tag (-a) is recommended as they store extra meta data over lightweight tags such as the author and date.

git tag -a v2.1.1 -m "Security patch to 2.1.1"

Sharing tags is similar to pushing branches. By default, git push will not push tags. Tags have to be explicitly passed to git push:

git push origin v2.1.1

The git flutter CLI tool has various helper features to help you apply these tags easily and consistently to your repository, for example:

$ git flutter tag major
Tag the current branch with a semantic version.

i Current branch ppb/develop was tagged v1.1.0-ppb.alpha.3 2 commits ago.
i The new tag version is v2.0.0-ppb.alpha.0
? Create and push tag v2.0.0-ppb.alpha.0 on ppb/develop? Yes
✔ Tag v2.0.0-ppb.alpha.0 applied to branch ppb/develop
✔ Tag v2.0.0-ppb.alpha.0 pushed to origin.

Tag v2.0.0-ppb.alpha.0 has been created.

The git flutter tag command helps to apply the next semver tag using any hints you provide and helps reduce the chance of user error.

$ git flutter tag --help
Tag the current branch with a semantic version.

Usage:
  git flutter tag [major | minor | patch | integration | <new version>] [flags]

Examples:
$ git flutter tag
$ git flutter tag patch
$ git flutter tag 2.4.1

Flags:
  -h, --help             help for tag
  -m, --message string   custom annotated tag commit message
  -s, --source string    working directory (default ".")
      --team string      team name
  -y, --yes              confirm yes to any interactive prompts

Global Flags:
      --no-network   do not perform network operations
  -v, --verbose      verbose log output

The git flutter command can be installed in less than 1 minute – try it today!