From 99261238c1494fcb9a192e7649a0ae5a23fefa9e Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Sat, 21 Sep 2024 14:52:27 +0200 Subject: [PATCH 01/10] Improve listing of version strategies in how-it-works.md --- docs/input/docs/learn/how-it-works.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index 36ba942451..75f3887631 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -19,8 +19,7 @@ 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. @@ -35,35 +34,36 @@ 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 +* `TaggedCommit` - Extracts version information from all tags on the branch which are valid, and not newer than the current commit. +* `VersionInBranchName` - Extracts version information from the branch name (e.g., `release/3.0.0` will find `3.0.0`) -* `ConfigNextVersionBaseVersionStrategy` - Returns the version from the +* `ConfiguredNextVersion` - Returns the version from the GitVersion.yaml file -* `MergeMessageBaseVersionStrategy` - Finds version numbers from merge messages +* `MergeMessage` - 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) +* `TrackReleaseBranches` - TODO: Document this +* `Mainline` - TODO: Document this 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. From 5cd8b00b635b5a8442d3db575039d27a9f04456f Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Sat, 21 Sep 2024 14:05:11 +0200 Subject: [PATCH 02/10] Fix Edit Diagram link on how-it-works.md --- docs/input/docs/learn/how-it-works.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index 75f3887631..a50b26a12b 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -25,9 +25,9 @@ GitVersion has three distinct steps for calculating versions in v3. 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. From c733fbbe90cf9dfc66799ca1e3ef6e9917616cf7 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Sat, 21 Sep 2024 14:07:16 +0200 Subject: [PATCH 03/10] Use correct target name in docs build instructions readme --- docs/readme.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/readme.md b/docs/readme.md index 6d89c8deaf..a4ab0556a0 100644 --- a/docs/readme.md +++ b/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/ From 0d366954b4bb134f7a68139c0c0b5c4656ea8516 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Mon, 23 Sep 2024 20:02:40 +0200 Subject: [PATCH 04/10] Replace TrunkBased strategy listing with Mainline --- docs/input/docs/reference/mdsource/configuration.source.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/input/docs/reference/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md index 74b76fa054..6a29b96272 100644 --- a/docs/input/docs/reference/mdsource/configuration.source.md +++ b/docs/input/docs/reference/mdsource/configuration.source.md @@ -558,7 +558,7 @@ Specifies which version strategy implementation (one ore more) will be used to d - TaggedCommit - TrackReleaseBranches - VersionInBranchName -- TrunkBased +- Mainline [1145]: https://github.com/GitTools/GitVersion/issues/1145 [1366]: https://github.com/GitTools/GitVersion/issues/1366 From c3bf45b4f7f94242e15752b6a4e103e145e709f8 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Mon, 23 Sep 2024 19:55:28 +0200 Subject: [PATCH 05/10] Update description of Mainline strategy in how-it-works --- docs/input/docs/learn/how-it-works.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index a50b26a12b..0a13b5f38b 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -38,7 +38,8 @@ simply to show what happens if the check is true. Currently we have the following strategies: -* `TaggedCommit` - Extracts version information from all tags on the branch which are valid, and not newer than the current commit. +* `TaggedCommit` - Extracts version information from all tags on the branch which are valid, + and not newer than the current commit. * `VersionInBranchName` - Extracts version information from the branch name (e.g., `release/3.0.0` will find `3.0.0`) * `ConfiguredNextVersion` - Returns the version from the @@ -49,7 +50,7 @@ Currently we have the following strategies: 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) * `TrackReleaseBranches` - TODO: Document this -* `Mainline` - TODO: Document this +* `Mainline` - Increments the version on every commit for branches configured with `mode: Mainline` Each strategy needs to return an instance of `BaseVersion` which has the following properties: From 05d11f5633ad593f6a091eadcb24c2438c0cb622 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Thu, 3 Oct 2024 17:20:30 +0200 Subject: [PATCH 06/10] Update description of TrackReleaseBranches version strategy --- docs/input/docs/learn/how-it-works.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index 0a13b5f38b..e27bf3aecb 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -49,7 +49,9 @@ Currently we have the following strategies: * `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) -* `TrackReleaseBranches` - TODO: Document this +* `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) * `Mainline` - Increments the version on every commit for branches configured with `mode: Mainline` Each strategy needs to return an instance of `BaseVersion` which has the From e18d6b1929afec404cbb7e3121dc007f1d88041f Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Thu, 3 Oct 2024 17:21:27 +0200 Subject: [PATCH 07/10] fixup! Update description of Mainline strategy in how-it-works --- docs/input/docs/learn/how-it-works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index e27bf3aecb..aa1a57c959 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -52,7 +52,7 @@ Currently we have the following strategies: * `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) -* `Mainline` - Increments the version on every commit for branches configured with `mode: Mainline` +* `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: From 6f76020a0cf627991ccc02983040ab8baac90422 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Fri, 11 Oct 2024 18:08:57 +0200 Subject: [PATCH 08/10] Clarify version strategy order in documentation Updated the configuration documentation to specify that the order in which version strategies are specified does not matter. --- docs/input/docs/reference/mdsource/configuration.source.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/input/docs/reference/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md index 6a29b96272..d913b67c6b 100644 --- a/docs/input/docs/reference/mdsource/configuration.source.md +++ b/docs/input/docs/reference/mdsource/configuration.source.md @@ -550,7 +550,9 @@ 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 From 1750d00f7889b430d1a7fcfa4a0c787d099ebb07 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Fri, 11 Oct 2024 18:10:47 +0200 Subject: [PATCH 09/10] Further document Fallback strategy --- docs/input/docs/learn/how-it-works.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index aa1a57c959..f8c3368416 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -48,7 +48,8 @@ Currently we have the following strategies: (e.g., `Merge 'release/3.0.0' into 'main'` will return `3.0.0`) * `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. * `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) From 5f4ca13cd8682de09dca7b9c0df2133172966022 Mon Sep 17 00:00:00 2001 From: Bob Loblaw Date: Fri, 11 Oct 2024 18:11:56 +0200 Subject: [PATCH 10/10] Re-order strategies in how-it-works to match rest of documentation pages --- docs/input/docs/learn/how-it-works.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md index f8c3368416..03391ae1e4 100644 --- a/docs/input/docs/learn/how-it-works.md +++ b/docs/input/docs/learn/how-it-works.md @@ -38,21 +38,20 @@ simply to show what happens if the check is true. Currently we have the following strategies: -* `TaggedCommit` - Extracts version information from all tags on the branch which are valid, - and not newer than the current commit. -* `VersionInBranchName` - Extracts version information from the - branch name (e.g., `release/3.0.0` will find `3.0.0`) -* `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`) * `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 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) + 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