These examples are illustrating the usage of the supported GitHubFlow workflow
in GitVersion. To enable this workflow, the builtin template
GitHubFlow/v1 needs to be referenced in the
configuration as follows:
workflow: GitHubFlow/v1
calculation:
mode: ContinuousDelivery
Where
the continuous deployment mode for no branches,
the continuous delivery mode for
main branch and
the manual deployment mode
for release, feature and unknown branches are specified.
This configuration allows you to publish CI (Continuous Integration) builds
from main branch to an artifact repository.
All other branches are manually published. Read more about this at
version increments.
The continuous delivery mode has been used for the main branch in this
examples (specified as a fallback on the root
configuration layer) to illustrate how the version increments are applied.
In production context the continuous deployment mode might be a better
option when e.g. the release process is automated or the commits are tagged
by the pipeline automatically.
Feature Branch
Feature branches can be used in the GitHubFlow workflow to implement a
feature or fix a bug in an isolated environment. Feature branches will take
the feature
branch name and use that as the pre-release label. Feature branches will be
created from a main or release branch.
Create feature branch from main
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant feature as feature/foo
main->>feature: branch from main
activate feature
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 1.2.1
rect rgb(211, 211, 211)
Note over main: 1.2.1
end
main->>feature: merge
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.2-foo.1+2
end
feature->>feature: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over feature: 1.3.0-foo.1+3
end
feature->>feature: tag 2.0.0-foo.1
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
feature->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.0.0-PullRequest2.5
end
destroy pull
main--xpull: delete branch
feature->>main: merge
Note over feature: Feature branches should
be deleted once merged
destroy feature
main--xfeature: delete branch
rect rgb(211, 211, 211)
Note over main: 2.0.0-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.0.0-6
end
main->>main: tag 2.0.0
rect rgb(211, 211, 211)
Note over main: 2.0.0
end
After the feature branch is merged, the version on main is 2.0.0-5.
This is due to main running in continuous delivery mode. If main was
configured to use continuous deployment the version would be 2.0.0.
Mainline version strategy comparison
The same feature branch history produces different versions when the
Mainline version strategy is
used. In particular, the final untagged commit on main becomes 2.0.1-1
rather than 2.0.0-6:
sequenceDiagram
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.0-1
end
create participant feature as feature/foo
main->>feature: branch from main
activate feature
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>feature: merge
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.2-foo.1+2
end
feature->>feature: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over feature: 1.3.0-foo.1+3
end
feature->>feature: tag 2.0.0-foo.1
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
feature->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.0.0-PullRequest2.5
end
destroy pull
main--xpull: delete branch
feature->>main: merge
Note over feature: Feature branches should
be deleted once merged
destroy feature
main--xfeature: delete branch
rect rgb(211, 211, 211)
Note over main: 2.0.0-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.0.1-1
end
The other Mainline integration scenarios use the same branch histories as the
release examples below, so they are not repeated here. See
DocumentationSamplesForGitHubFlow.cs
for the complete executable scenarios and their expected versions.
Release Branches
Release branches are used for major, minor and patch releases to stabilize a RC
(Release Candidate) or to integrate features/hotfixes (in parallel) targeting
different
iterations. Release branches are taken from main and will
be merged back afterwards. Finally the main branch is tagged with the
released version.
Release branches can be used in the GitHubFlow as well as GitFlow workflow.
Sometimes you
want to start on a large feature which may take a while to stabilize so you want
to keep it off main. In these scenarios you can either create a long lived
feature branch (if you do not know the version number this large feature will go
into, and it's non-breaking) otherwise you can create a release branch for the
next major version. You can then submit pull requests to the long lived feature
branch or the release branch.
Create release branch
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant release as release/next
main->>release: branch from main
activate release
deactivate main
rect rgb(211, 211, 211)
Note over release: 1.2.1-beta.1+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 1.2.1-beta.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 1.2.1
rect rgb(211, 211, 211)
Note over main: 1.2.1
end
main->>release: merge
deactivate main
rect rgb(211, 211, 211)
Note over release: 1.2.2-beta.1+2
end
release->>release: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over release: 1.3.0-beta.1+3
end
release->>release: tag 1.3.1-beta.1
rect rgb(211, 211, 211)
Note over release: 1.3.1-beta.2+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 1.3.1-beta.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
release->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 1.3.1-PullRequest2.5
end
destroy pull
main--xpull: delete branch
release->>main: merge
Note over release: Release branches should
be deleted once merged
destroy release
main--xrelease: delete branch
rect rgb(211, 211, 211)
Note over main: 1.3.1-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.3.1-6
end
main->>main: tag 1.3.1
rect rgb(211, 211, 211)
Note over main: 1.3.1
end
Create release branch with version
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant release as release/2.2.1
main->>release: branch from main
activate release
deactivate main
rect rgb(211, 211, 211)
Note over release: 2.2.1-beta.1+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 2.2.1-beta.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 2.2.1
rect rgb(211, 211, 211)
Note over main: 2.2.1
end
main->>release: merge
deactivate main
rect rgb(211, 211, 211)
Note over release: 2.2.2-beta.1+2
end
release->>release: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over release: 2.3.0-beta.1+3
end
release->>release: tag 2.3.1-beta.1
rect rgb(211, 211, 211)
Note over release: 2.3.1-beta.2+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 2.3.1-beta.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
release->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.3.1-PullRequest2.5
end
destroy pull
main--xpull: delete branch
release->>main: merge
Note over release: Release branches should
be deleted once merged
destroy release
main--xrelease: delete branch
rect rgb(211, 211, 211)
Note over main: 2.3.1-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.3.1-6
end
main->>main: tag 2.3.1
rect rgb(211, 211, 211)
Note over main: 2.3.1
end
To Contribute
Source
The diagrams are generated from DocumentationSamplesForGitHubFlow.cs. After
changing a scenario, run the GenerateMermaidSources Cake task, inspect the
updated Mermaid source, and run the ValidateMermaidDiagrams Cake task before
committing it.