A description of the recommended semantic versioning conventions.
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:
majoris 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.
minoris 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.
patchis the patch version number (integer). A patch change is a hotfix usually executed under incident conditions.
teamis the team code (string). This can be omitted when there is only a single owning team.
phaseis the release phase (
betaor not present for production).
integrationis an integer that indicates pre-release progression e.g. cumulative number of features, commits or similar.
buildis an integer that indicates build number (omitted if un-used).
By convention the version number is prefixed by a
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.
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.1than upgrading from version
- 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.0while other users on
v2.1.1can 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.
Recommended branching model patterns explained in under 7 minutes!
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
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.
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
git flutter command can be installed in less than 1 minute – try it today!