Merge pull request #4220 from selfdocumentingcode/docs/some-fixes

Improve documentation around version strategies

Author: arturcic

docs/input/docs/learn/how-it-works.md

@@ -19,51 +19,54 @@ GitVersion has three distinct steps for calculating versions in v3.
 1. If the current commit is tagged, the tag is used and build metadata
     (excluding commit count) is added. The other two steps will not execute.
 2. A set of strategies are evaluated to decide on the base version and some
-    metadata about that version.  These strategies include HighestReachableTag,
-    NextVersionInConfig, MergedBranchWithVersion, VersionInBranchName etc.
+    metadata about that version. See [Version Strategies](#version-strategies)
 3. The highest base version is selected, using that base version as the new
     version is calculated.
 
 Visually it looks something like this:
 
-![Version Calculation](https://www.plantuml.com/plantuml/png/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1\_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK\_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea\_0G00)
+![Version Calculation](https://www.plantuml.com/plantuml/png/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea_0G00)
 
-[Edit Diagram](https://www.plantuml.com/plantuml/form?url=https://www.plantuml.com/plantuml/png/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1\_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK\_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea\_0G00)
+[Edit Diagram](https://www.plantuml.com/plantuml/uml/fLCxJyCm4DxzAsuib4P914i69De1CS38Vd6kYIN7ZcodK8aVp-KX6Y2fKCbY9NV-7lVb2WoOeoVOMRDNfH0lz1vUoNbbpGwrR3K6ws1p3rlk-bN8u972f2AC3GHEbLN8m1D1Jjg-mPuXAZvx9kL1ZW1KY5dOZczMI0Pf54VnHtf7jpaAWJg0sW-uXw4PK3Eb1sMaevfCW6i1_0m6po1l7HfPJUxvu5XYUOHLWq5MLptCudmMK9--u5glJ0dIEaVo1Dw3JgVM6Km4cM9mzyrQXHuQHnj7chhl0JcnIrHjno1wiWtgfi8eWVK_7OQAmBHrJWvORFVM2PmrE7AcWZGh-Lj0FvptVvLiUPnCdG_XhNhOov9wQ1fzv7nw5S5EwSvw6CDQNfnMwUAP0XQyQpj70nkx3Nn3p5NFY9IshbNWepKi8ublWFiSPkC0ee8El75Dv5aOxqZQBScbWpWn0Pe2wb6aM1p4Eea_0G00)
 
 **\*** Some strategies allow the version to be incremented, others don't. More
 info below.
 **+** This version is out of context with the rest of the example. It is here
 simply to show what happens if the check is true.
 
-### Base Version Strategies
+### Version Strategies
 
 Currently we have the following strategies:
 
-* `HighestTagBaseVersionStrategy` - Finds the highest reachable tag from the
-    current branch
-* `VersionInBranchBaseVersionStrategy` - Extracts version information from the
-    branch name (e.g., `release/3.0.0` will find `3.0.0`)
-* `ConfigNextVersionBaseVersionStrategy` - Returns the version from the
-    GitVersion.yaml file
-* `MergeMessageBaseVersionStrategy` - Finds version numbers from merge messages
-    (e.g., `Merge 'release/3.0.0' into 'main'` will return `3.0.0`)
-* `FallbackBaseVersionStrategy` - Always returns 0.0.0 and will be used for
+* `Fallback` - Always returns 0.0.0 and will be used for
     calculating the next version which is dependent on the increment strategy of
- the effected branch (e.g. on main the next version is 0.0.1 or on develop it is 0.1.0)
+    the effected branch (e.g. on main the next version is 0.0.1 or on develop it is 0.1.0).
+    The fallback strategy only applies if no other selected strategy returns a base version.
+* `ConfiguredNextVersion` - Returns the version from the GitVersion.yaml file
+* `MergeMessage` - Finds version numbers from merge messages
+    (e.g., `Merge 'release/3.0.0' into 'main'` will return `3.0.0`)
+* `TaggedCommit` - Extracts version information from all tags on the branch which are valid,
+    and not newer than the current commit.
+* `TrackReleaseBranches` - Considers the base version extracted from release branches when
+    calculating the next version for branches configured with `track-release-branches: true`
+    (part of default configuration for `develop` branch in `GitFlow` workflow)
+* `VersionInBranchName` - Extracts version information from the
+    branch name (e.g., `release/3.0.0` will find `3.0.0`)
+* `Mainline` - Increments the version on every commit for branches configured with `is-main-branch: true`
 
 Each strategy needs to return an instance of `BaseVersion` which has the
 following properties:
 
 * `Source` - Description of the source (e.g., `Merge message 'Merge 'release/3.0.0' into 'main'`)
 * `ShouldIncrement` - Some strategies should have the version incremented,
-    others do not (e.g., `ConfigNextVersionBaseVersionStrategy` returns false,
-    `HighestTagBaseVersionStrategy` returns true)
+    others do not (e.g., `ConfiguredNextVersion` returns false,
+    `TaggedCommit` returns true)
 * `SemanticVersion` - SemVer of the base version strategy
 * `BaseVersionSource` - SHA hash of the source. Commits will be counted from
-    this hash. Can be null (e.g., `ConfigNextVersionBaseVersionStrategy` returns
+    this hash. Can be null (e.g., `ConfiguredNextVersion` returns
     null).
 * `BranchNameOverride` - When `useBranchName` or `{BranchName}` is used in the
     tag configuration, this allows the branch name to be changed by a base version.
-    `VersionInBranchBaseVersionStrategy` uses this to strip out anything before the
+    `VersionInBranchName` uses this to strip out anything before the
     first `-` or `/.` so `foo` ends up being evaluated as `foo`. If in doubt, just
     use null.

docs/input/docs/reference/mdsource/configuration.source.md

@@ -550,15 +550,17 @@ Example of invalid `Strict`, but valid `Loose`
 
 ### strategies
 
-Specifies which version strategy implementation (one ore more) will be used to determine the next version. Following values are supported and can be combined:
+Specifies which version strategy implementation (one or more) will be used to determine the next version.
+These strategies can be combined, and the order in which they are specified does not matter.
+The configuration accepts the following values:
 
 - Fallback
 - ConfiguredNextVersion
 - MergeMessage
 - TaggedCommit
 - TrackReleaseBranches
 - VersionInBranchName
-- TrunkBased
+- Mainline
 
 [1145]: https://github.com/GitTools/GitVersion/issues/1145
 [1366]: https://github.com/GitTools/GitVersion/issues/1366

docs/readme.md

@@ -21,7 +21,7 @@ To serve up the documentation locally, you need to run the following
 commands:
 
 ```shell
-./build.ps1 -Stage build -Target PrepareBuild
+./build.ps1 -Stage build -Target BuildPrepare
 ./build.ps1 -Stage build -Target Build
 ./build.ps1 -Stage docs -Target PreviewDocs
 ```
@@ -32,7 +32,7 @@ On Windows, you need to run the following commands in a PowerShell
 terminal:
 
 ```shell
-./build.ps1 -Stage build -Target PrepareBuild
+./build.ps1 -Stage build -Target BuildPrepare
 ./build.ps1 -Stage build -Target Build
 ./build.ps1 -Stage docs -Target PreviewDocs
 ```
@@ -43,14 +43,14 @@ First you need to [install PowerShell on macOS][ps-mac] or [Linux][ps-linux],
 then execute the following commands:
 
 ```shell
-./build.ps1 -Stage build -Target PrepareBuild
+./build.ps1 -Stage build -Target BuildPrepare
 ./build.ps1 -Stage build -Target Build
 ./build.ps1 -Stage docs -Target PreviewDocs
 ```
 
 After pressing enter, the documentation will be generated and then served under
-a local web server.  Information about the URL that can be used to view the docs
-will be shown in the output.  Copy/paste this URL into a browser window.
+a local web server. Information about the URL that can be used to view the docs
+will be shown in the output. Copy/paste this URL into a browser window.
 
 [gitversion.net]: https://gitversion.net/
 [forking]: https://guides.github.com/activities/forking/