Blog

We recently configured GitVersion for a library and expected it to be really straightforward. To our surprise, it was not! We checked every GitVersion example we could find, stack overflow, and the GitVersion documentation. None of the samples we found matched our workflows. Since publishing libraries with the GitHub flow is a standard use case, here is a sample GitVersion config.

Workflow

When a Pull-Request is merged, this triggers a release of the library without any further manual action. GitVersion calculates the current version number based on tags (highest priority) and merge commits/branch names.

1. We are using the GitHub flow, where all changes are merged back into the main branch (called ‘main’) after they have been verified. That means there are no feature branches.
2. To determine the version we use branch names and merge commits.
3. Branches always branch off the main branch.
4. The main branch is protected, all changes are coming in via PRs. Since the GitVersion configuration is relying on the merge commit messages to calculate the version, squash or rebase merges are prohibited.
5. After changes are pushed to the main branch, the release package(s) are built and automatically pushed into the package repository.
6. Every time a change is pushed to another branch, the branch is built as a pre-release package(s) and pushed into the package repository. The pre-release tag contains the branch name and number of commits the branch is ahead of the main branch.

Branch Naming Conventions

GitVersion calculates the version based on the following branching name conventions:

To increase the major version we use tags, i.e. ‘v2.0.0’ which will take precedence over any version calculated from commits.

GitVersion Configuration

Here is a minimal GitVersion configuration that fulfills the purpose. You may want to extend the configuration, check the GitVersion documentation for more options.

Note: The GitVersion calculation will slow down over time without tags. Adding tags manually or during the release process will speed up the calculation.

mode: Mainline
merge-message-formats:
  ghmerge: ^Merge pull request \#(?<PullRequestNumber>\d+) from AngelaE\/(?<SourceBranch>.+)
branches:
  master:
    regex: (^main$)
    tag: ""
    increment: Patch
    is-release-branch: true
  feature:
    regex: ^feature?[/-]
    tag: useBranchName
    increment: Minor
  bugfix:
    regex: ^bugfix[/-]
    tag: useBranchName
    increment: Patch
    source-branches: ["main"]
  chore:
    regex: ^chore[/-]
    tag: useBranchName
    increment: None
    prevent-increment-of-merged-branch-version: true
    source-branches: ["main"]