Release version tagging

When a build is released commit must be tagged with release version tag. Release tags are identified as tags with a friendly name that matches the release tag format. This format is used to extract the released version (<major>.<minor>.<patch>).

Workflow

Tip

For the end user to best benefit from Semmantic Versioning a release should be defined as when a build is made available to users that will benefit from knowing if the build has breaking changes, features, or only fixes.

That end user may be an internal customer (such as tested or marketing or other teams) of external users like the community. Often marketing are focused on a product release/version identified by marketing drived naming versioning. A release, for semantic versioning, may be when delivered to a testing team.

Rebuilds of the commit with a release version tag will produce builds with the same released base version but with different build numbers in the full version metadata.

The commit being tagged does not need to be the most recent commit on a release branch. If it is not the most recent then rebuilding following commits will result in their versions following the released version according to semantic versioning rules.

Default release tag format

The default release tag format is:

  v<major>.<minor>.<patch>

Or, in regular expression format:

  ^v(?<version>\d+\.\d+\.\d+)"

Default release version tag friendly name example matching:

✔ Will match	❌ With NOT match
v1.2.3 v1.2.3 with red grapes	1.2.3 release v1.2.3 release v1.2

For example, tag friendly names that will match this default format include:

  v1.2.3
  v1.2.3 our big beautiful pink release

Configuring the release tag format

The release tag format is configurable by setting the build property Git2SemVer_ReleaseTagFormat to a regular expressing that will match tags that have the desired friendly name.

Important

This regular expression must:

• Contain the version placeholder text %VERSION%.
• NOT start with the reserved prefixes: ^, tag: , or .gsm.

The default release tag format equivalent to v%VERSION%. The Git2SemVer_ReleaseTagFormat build property is set the project file or in a directory build properties file like Directory.Build.props.

For example:

<PropertyGroup>
    <Git2SemVer_ReleaseTagFormat>MyRelease %VERSION%</Git2SemVer_ReleaseTagFormat>
</PropertyGroup>

Examples:

Git2SemVer_ReleaseTagFormat	✔ Will match	❌ With NOT match
%VERSION%	1.2.3 1.2.3 with red grapes	v1.2.3 release 1.2.3 release 1.2
release: %VERSION%	release: 1.2.3 release: 1.2.3 with red apples	release 1.2.3 my release: 1.2.3
.*release: %VERSION%	release: 1.2.3 my release: 1.2.3 green apples release: 1.2.3	release 1.2.3