Skip to content

Commit a4abf52

Browse files
arturcicarturcic
committed
docs: document trunk-based workflow with executable examples
1 parent 205c0ca commit a4abf52

13 files changed

Lines changed: 376 additions & 5 deletions

‎build/docs/Utilities/Mermaid.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ public void GenerateMermaidSources(bool check)
6161
context.DotNetTest(DocumentationTestsProject.FullPath, new DotNetTestSettings
6262
{
6363
PathType = DotNetTestPathType.Project,
64-
Filter = "FullyQualifiedName~DocumentationSamplesForGitFlow|FullyQualifiedName~DocumentationSamplesForGitHubFlow",
64+
Filter = "FullyQualifiedName~DocumentationSamplesForGitFlow|FullyQualifiedName~DocumentationSamplesForGitHubFlow|FullyQualifiedName~DocumentationSamplesForTrunkBased",
6565
WorkingDirectory = context.MakeAbsolute(Paths.Root),
6666
EnvironmentVariables = new Dictionary<string, string>
6767
{

‎docs/diagrams/DocumentationSamplesForTrunkBased_CommitMessageIncrements.mmd‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
sequenceDiagram
2+
activate main
3+
main->>main: commit
4+
main->>main: tag 1.2.0
5+
rect rgb(211, 211, 211)
6+
Note over main: 1.2.0
7+
end
8+
main->>main: Commit 'Fix a bug +semver: patch'
9+
rect rgb(211, 211, 211)
10+
Note over main: 1.2.1
11+
end
12+
main->>main: Commit 'Add an API +semver: minor'
13+
rect rgb(211, 211, 211)
14+
Note over main: 1.3.0
15+
end
16+
main->>main: Commit 'Break an API +semver: major'
17+
rect rgb(211, 211, 211)
18+
Note over main: 2.0.0
19+
end
20+
main->>main: commit
21+
rect rgb(211, 211, 211)
22+
Note over main: 2.0.1
23+
end

‎docs/diagrams/DocumentationSamplesForTrunkBased_DirectCommitsAndReleaseTags.mmd‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
sequenceDiagram
2+
activate main
3+
main->>main: commit
4+
main->>main: tag 1.2.0
5+
rect rgb(211, 211, 211)
6+
Note over main: 1.2.0
7+
end
8+
main->>main: commit
9+
rect rgb(211, 211, 211)
10+
Note over main: 1.2.1
11+
end
12+
main->>main: commit
13+
rect rgb(211, 211, 211)
14+
Note over main: 1.2.2
15+
end
16+
main->>main: tag v1.2.2
17+
rect rgb(211, 211, 211)
18+
Note over main: 1.2.2
19+
end
20+
main->>main: commit
21+
rect rgb(211, 211, 211)
22+
Note over main: 1.2.3
23+
end

‎docs/diagrams/DocumentationSamplesForTrunkBased_feature_BranchMerge.mmd‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
sequenceDiagram
2+
activate main
3+
main->>main: commit
4+
main->>main: tag 1.2.0
5+
rect rgb(211, 211, 211)
6+
Note over main: 1.2.0
7+
end
8+
create participant feature_foo as feature/foo
9+
main->>feature_foo: branch from main
10+
deactivate main
11+
activate feature_foo
12+
feature_foo->>feature_foo: commit
13+
rect rgb(211, 211, 211)
14+
Note over feature_foo: 1.3.0-foo.1
15+
end
16+
feature_foo->>feature_foo: commit
17+
rect rgb(211, 211, 211)
18+
Note over feature_foo: 1.3.0-foo.2
19+
end
20+
activate main
21+
feature_foo->>main: merge
22+
deactivate feature_foo
23+
destroy feature_foo
24+
main--xfeature_foo: delete branch
25+
rect rgb(211, 211, 211)
26+
Note over main: 1.3.0
27+
end
28+
main->>main: commit
29+
rect rgb(211, 211, 211)
30+
Note over main: 1.3.1
31+
end

‎docs/diagrams/DocumentationSamplesForTrunkBased_hotfix_BranchMerge.mmd‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
sequenceDiagram
2+
activate main
3+
main->>main: commit
4+
main->>main: tag 1.2.0
5+
rect rgb(211, 211, 211)
6+
Note over main: 1.2.0
7+
end
8+
create participant hotfix_fix as hotfix/fix
9+
main->>hotfix_fix: branch from main
10+
deactivate main
11+
activate hotfix_fix
12+
hotfix_fix->>hotfix_fix: commit
13+
rect rgb(211, 211, 211)
14+
Note over hotfix_fix: 1.2.1-fix.1
15+
end
16+
hotfix_fix->>hotfix_fix: commit
17+
rect rgb(211, 211, 211)
18+
Note over hotfix_fix: 1.2.1-fix.2
19+
end
20+
activate main
21+
hotfix_fix->>main: merge
22+
deactivate hotfix_fix
23+
destroy hotfix_fix
24+
main--xhotfix_fix: delete branch
25+
rect rgb(211, 211, 211)
26+
Note over main: 1.2.1
27+
end
28+
main->>main: commit
29+
rect rgb(211, 211, 211)
30+
Note over main: 1.2.2
31+
end

‎docs/input/docs/learn/branching-strategies/index.cshtml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ RedirectFrom:
88
- docs/examples
99
---
1010

11-
<p>Start by <a href="/docs/usage/choose-workflow">choosing a workflow</a>. The examples below illustrate GitFlow and GitHubFlow histories; read each example with its configuration. For experimental trunk-based defaults, see <a href="/docs/reference/configuration#global-configuration">TrunkBased/preview1</a>.</p>
11+
<p>Start by <a href="/docs/usage/choose-workflow">choosing a workflow</a>. The examples below illustrate GitFlow, GitHubFlow, and <a href="/docs/learn/branching-strategies/trunkbased">TrunkBased/preview1</a> histories; read each example with its configuration. The <a href="/docs/learn/branching-strategies/trunkbased/examples">trunk-based examples</a> use the experimental preset without overrides.</p>
1212

1313
<img src="/docs/img/CommitGraph.png" alt="Commit graph">
1414

‎docs/input/docs/learn/branching-strategies/trunkbased/examples.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
Order: 50
3+
Title: Trunk-based examples
4+
---
5+
6+
All examples use the unmodified [TrunkBased preview preset](/docs/learn/branching-strategies/trunkbased):
7+
8+
```yaml
9+
workflow: TrunkBased/preview1
10+
```
11+
12+
Each scenario starts independently on `main` with a commit tagged `1.2.0`.
13+
The diagrams display asserted **FullSemVer** values.
14+
15+
## Direct commits and release tags
16+
17+
Two ordinary commits on main produce `1.2.1` and `1.2.2`. Tagging the latter
18+
`v1.2.2` preserves that version; the following commit produces `1.2.3`.
19+
GitVersion calculates these values; it does not create the release tags for you.
20+
Tag the commit you release, using the version you published.
21+
22+
<pre class="mermaid" aria-label="Trunk-based direct commits and release tags diagram">
23+
^"../../../../../diagrams/DocumentationSamplesForTrunkBased_DirectCommitsAndReleaseTags.mmd"
24+
</pre>
25+
26+
## Feature merge
27+
28+
Create `feature/foo` from the tagged main commit, make two commits, and merge
29+
it into main with `git merge --no-ff feature/foo`. The feature defaults to a
30+
Minor increment: the branch builds are `1.3.0-foo.1` and `1.3.0-foo.2`.
31+
The merge produces `1.3.0` on main, and the next ordinary main commit produces
32+
`1.3.1`. Delete the feature branch after merging.
33+
34+
<pre class="mermaid" aria-label="Trunk-based feature merge diagram">
35+
^"../../../../../diagrams/DocumentationSamplesForTrunkBased_feature_BranchMerge.mmd"
36+
</pre>
37+
38+
## Hotfix merge
39+
40+
Create `hotfix/fix` from the tagged main commit, make two commits, and merge
41+
it with `git merge --no-ff hotfix/fix`. The hotfix defaults to a Patch increment:
42+
branch builds are `1.2.1-fix.1` and `1.2.1-fix.2`. The merge produces
43+
`1.2.1` on main, and the next ordinary main commit produces `1.2.2`.
44+
Delete the hotfix branch after merging.
45+
46+
<pre class="mermaid" aria-label="Trunk-based hotfix merge diagram">
47+
^"../../../../../diagrams/DocumentationSamplesForTrunkBased_hotfix_BranchMerge.mmd"
48+
</pre>
49+
50+
## Commit-message increments
51+
52+
On main, the following sequence illustrates the enabled commit-message rules:
53+
54+
| Commit message | FullSemVer |
55+
| --- | --- |
56+
| `Fix a bug +semver: patch` | `1.2.1` |
57+
| `Add an API +semver: minor` | `1.3.0` |
58+
| `Break an API +semver: major` | `2.0.0` |
59+
| Ordinary commit | `2.0.1` |
60+
61+
The default patterns also accept `fix`, `feature`, and `breaking` as aliases
62+
for `patch`, `minor`, and `major`. See
63+
[version increments](/docs/reference/version-increments) for the configurable
64+
message patterns.
65+
66+
<pre class="mermaid" aria-label="Trunk-based commit-message increments diagram">
67+
^"../../../../../diagrams/DocumentationSamplesForTrunkBased_CommitMessageIncrements.mmd"
68+
</pre>
69+
70+
## Executable source
71+
72+
These diagrams come from
73+
[`DocumentationSamplesForTrunkBased.cs`](https://github.com/GitTools/GitVersion/blob/main/src/GitVersion.Core.Tests/IntegrationTests/DocumentationSamplesForTrunkBased.cs),
74+
which constructs `TrunkBasedConfigurationBuilder.New.Build()` in each scenario
75+
and asserts every displayed version. To update them, run the
76+
`GenerateMermaidSources` Cake task and then `ValidateMermaidDiagrams`.
77+
See [contributing examples](/docs/learn/branching-strategies/contribute-examples).

‎docs/input/docs/learn/branching-strategies/trunkbased/index.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
Order: 40
3+
Title: Trunk-based (preview)
4+
Description: Configure and evaluate the experimental TrunkBased workflow
5+
---
6+
7+
Use `TrunkBased/preview1` when your team integrates into one main branch,
8+
works directly on that branch or uses short-lived feature and hotfix branches,
9+
and wants versions calculated from that mainline history. Release tags record
10+
published versions; a separate develop or release branch is not required.
11+
12+
This preset is **experimental**. Evaluate it against representative histories
13+
before adopting it. Its defaults and behavior may change; it does not have the
14+
same compatibility guarantees as `GitFlow/v1` and `GitHubFlow/v1`.
15+
16+
## Start with the preset
17+
18+
Create `GitVersion.yml` at the repository root:
19+
20+
```yaml
21+
workflow: TrunkBased/preview1
22+
```
23+
24+
Inspect the resolved defaults and the version at your current commit:
25+
26+
```shell
27+
dotnet-gitversion --show-config
28+
dotnet-gitversion --show-variable FullSemVer
29+
```
30+
31+
The preset selects the `ConfiguredNextVersion` and `Mainline` calculation
32+
strategies. [Mainline](/docs/reference/modes/mainline) interprets commits and
33+
merges to calculate version increments; it is a strategy, not a deployment mode.
34+
You do not need to override `strategies` or set `next-version` to use this preset.
35+
36+
For overrides, follow the [v7 configuration layout](/docs/reference/configuration#v7-configuration-layout):
37+
`workflow` stays at the root, version-calculation settings go under
38+
`calculation`, and output settings go under `output`.
39+
40+
## Branch defaults
41+
42+
These are the defaults of `TrunkBased/preview1`, without overrides:
43+
44+
| Branch type | Recognized names | Increment | Deployment mode | Pre-release label |
45+
| --- | --- | --- | --- | --- |
46+
| main | `main`, `master` | Patch | ContinuousDeployment | Empty |
47+
| feature | `feature/foo`, `features/foo` | Minor | ContinuousDelivery | Branch name, such as `foo` |
48+
| hotfix | `hotfix/fix`, `hotfixes/fix` | Patch | ContinuousDelivery | Branch name, such as `fix` |
49+
| pull-request | `pull/42`, `pull-requests/42`, `pr/42` (including merge refs) | Inherit | ContinuousDelivery | `PullRequest42` |
50+
| unknown | Other names | Patch | ContinuousDelivery | Branch name |
51+
52+
The feature, hotfix, and pull-request patterns also accept `-` as the separator.
53+
Feature, hotfix, and unknown branches list `main` as their source branch type;
54+
pull requests list `main`, `feature`, and `hotfix`. Hotfix branches are marked
55+
`is-release-branch: true`. The preset has no dedicated `develop`, `release`, or
56+
`support` branch configuration: those names use the unknown-branch fallback.
57+
58+
On `main`, ContinuousDeployment produces versions without a pre-release suffix.
59+
An untagged commit can therefore have a stable-looking version; that alone does
60+
not mean it has been published. Feature and hotfix builds carry branch labels.
61+
Commit-message incrementing is enabled, and the default tag prefix accepts
62+
both `1.2.0` and `v1.2.0`.
63+
64+
See the [complete built-in configuration](/docs/reference/configuration#global-configuration)
65+
for the exact regular expressions, merge handling, and output weights. Do not
66+
substitute the outputs of customized GitFlow Mainline examples for this preset.
67+
68+
## Try representative histories
69+
70+
The [worked examples](examples) show direct commits on main, feature and hotfix
71+
merges, release tags, and commit-message increments using this exact preset.
72+
Compare those histories with your repository, including your actual merge
73+
policy, before switching workflows. Squash and fast-forward merges produce
74+
different histories from the explicit merge commits in these examples.

‎docs/input/docs/reference/configuration.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,17 @@ every workflow uses the same deployment mode.
1616
To see the effective configuration (defaults and overrides), you can run
1717
`gitversion --show-config`.
1818

19+
## Configuration tool
20+
21+
The interactive configuration tool (`gitversion init`) was removed in
22+
GitVersion v6.0.0. The [removal commit](https://github.com/GitTools/GitVersion/commit/09014f1af2367d79d53919c759a82ea998d9db6c)
23+
removed the init wizard and its command handling. Create `GitVersion.yml`
24+
manually, [choose a workflow](/docs/usage/choose-workflow), and inspect the
25+
resolved settings with `gitversion --show-config`. Follow
26+
[Configure GitVersion](/docs/usage/configure) for current configuration guidance,
27+
or the [trunk-based guide](/docs/learn/branching-strategies/trunkbased) to try
28+
`TrunkBased/preview1`.
29+
1930
## v7 configuration layout
2031

2132
GitVersion v7 separates version **calculation** from version **output**. Put
@@ -102,7 +113,7 @@ The following supported workflow configurations are available in GitVersion and
102113

103114
* GitFlow (GitFlow/v1)
104115
* GitHubFlow (GitHubFlow/v1)
105-
* TrunkBased (TrunkBased/preview1, experimental preview)
116+
* [TrunkBased](/docs/learn/branching-strategies/trunkbased) (`TrunkBased/preview1`, experimental preview; [worked examples](/docs/learn/branching-strategies/trunkbased/examples))
106117

107118
Example of using a `GitHubFlow` workflow with a different `tag-prefix`:
108119

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

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,17 @@ every workflow uses the same deployment mode.
1616
To see the effective configuration (defaults and overrides), you can run
1717
`gitversion --show-config`.
1818

19+
## Configuration tool
20+
21+
The interactive configuration tool (`gitversion init`) was removed in
22+
GitVersion v6.0.0. The [removal commit](https://github.com/GitTools/GitVersion/commit/09014f1af2367d79d53919c759a82ea998d9db6c)
23+
removed the init wizard and its command handling. Create `GitVersion.yml`
24+
manually, [choose a workflow](/docs/usage/choose-workflow), and inspect the
25+
resolved settings with `gitversion --show-config`. Follow
26+
[Configure GitVersion](/docs/usage/configure) for current configuration guidance,
27+
or the [trunk-based guide](/docs/learn/branching-strategies/trunkbased) to try
28+
`TrunkBased/preview1`.
29+
1930
## v7 configuration layout
2031

2132
GitVersion v7 separates version **calculation** from version **output**. Put
@@ -102,7 +113,7 @@ The following supported workflow configurations are available in GitVersion and
102113

103114
* GitFlow (GitFlow/v1)
104115
* GitHubFlow (GitHubFlow/v1)
105-
* TrunkBased (TrunkBased/preview1, experimental preview)
116+
* [TrunkBased](/docs/learn/branching-strategies/trunkbased) (`TrunkBased/preview1`, experimental preview; [worked examples](/docs/learn/branching-strategies/trunkbased/examples))
106117

107118
Example of using a `GitHubFlow` workflow with a different `tag-prefix`:
108119

0 commit comments

Comments
 (0)