Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve documentation around version strategies #4220

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Improve documentation around version strategies #4220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9926123
Improve listing of version strategies in how-it-works.md
selfdocumentingcode Sep 21, 2024
5cd8b00
Fix Edit Diagram link on how-it-works.md
selfdocumentingcode Sep 21, 2024
c733fbb
Use correct target name in docs build instructions readme
selfdocumentingcode Sep 21, 2024
0d36695
Replace TrunkBased strategy listing with Mainline
selfdocumentingcode Sep 23, 2024
c3bf45b
Update description of Mainline strategy in how-it-works
selfdocumentingcode Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 16 additions & 15 deletions docs/input/docs/learn/how-it-works.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,51 +19,52 @@ 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
* `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` - 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:

* `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.
2 changes: 1 addition & 1 deletion docs/input/docs/reference/mdsource/configuration.source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions docs/readme.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you also include the details for MarkdownSnippets that converts the *.source.md into *.md files in this readme?
This tool is used to embed some files into md files

https://github.com/GitTools/GitVersion/blob/main/.github/workflows/mkdocs.yml#L24-L28

Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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
```
Expand All @@ -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/
Expand Down