From 197ba00f149c4b0adfde709cd93a1d362ec4dac1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Asbj=C3=B8rn=20Ulsberg?= Date: Thu, 3 Feb 2022 16:11:43 +0100 Subject: [PATCH] `BuildMetaData` doesn't increment with every build Clarify that `BuildMetaData` does not increment with every build. --- docs/input/docs/reference/variables.md | 2 +- docs/input/docs/reference/version-increments.md | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/input/docs/reference/variables.md b/docs/input/docs/reference/variables.md index 80615bc835..bb52759a96 100644 --- a/docs/input/docs/reference/variables.md +++ b/docs/input/docs/reference/variables.md @@ -60,7 +60,7 @@ Each property of the above JSON document is described in the below table. | `PreReleaseLabelWithDash` | The pre-release label prefixed with a dash. | | `PreReleaseNumber` | The pre-release number. | | `WeightedPreReleaseNumber` | A summation of branch specific `pre-release-weight` and the `PreReleaseNumber`. Can be used to obtain a monotonically increasing version number across the branches. | -| `BuildMetaData` | The build metadata, usually representing number of commits since the `VersionSourceSha`. | +| `BuildMetaData` | The build metadata, usually representing number of commits since the `VersionSourceSha`. Despite its name, will not increment for every build. | | `BuildMetaDataPadded` | The `BuildMetaData` padded with `0` up to 4 digits. | | `FullBuildMetaData` | The `BuildMetaData` suffixed with `BranchName` and `Sha`. | | `MajorMinorPatch` | `Major`, `Minor` and `Patch` joined together, separated by `.`. | diff --git a/docs/input/docs/reference/version-increments.md b/docs/input/docs/reference/version-increments.md index 0a75f14776..d81d053d38 100644 --- a/docs/input/docs/reference/version-increments.md +++ b/docs/input/docs/reference/version-increments.md @@ -15,9 +15,9 @@ version. ## Approach -Semantic Versioning is all about _releases_, not builds. This means that the -version only increases after you release, this directly conflicts with the -concept of published CI builds. When you release the next version of your +Semantic Versioning is all about _releases_, not commits or builds. This means +that the version only increases after you release, this directly conflicts with +the concept of published CI builds. When you release the next version of your library/app/website/whatever you should only increment major/minor or patch then reset all lower parts to 0, for instance given `1.0.0`, the next release should be either `2.0.0`, `1.1.0` or `1.0.1`. @@ -26,7 +26,7 @@ Because of this, GitVersion works out what the next SemVer of your app is on each commit. When you are ready to release, you simply deploy the latest built version and tag the commit it was created from. This practice is called [continuous delivery][continuous-delivery]. GitVersion will increment the -_metadata_ for each build so you can tell builds apart. For example `1.0.0+5` +_metadata_ for each commit so you can tell them apart. For example `1.0.0+5` followed by `1.0.0+6`. It is important to note that build metadata _is not part of the semantic version; it is just metadata!_. @@ -34,9 +34,9 @@ All this effectively means that GitVersion will produce the same version NuGet package each commit until you tag a release. This causes problems for people as NuGet and other package managers do not -support multiple packages with the same version with only different metadata. -There are a few ways to handle this problem depending on what your requirements -are: +support multiple packages with the same version where only the metadata is +different. There are a few ways to handle this problem depending on what your +requirements are: ### 1. GitFlow