Generating Semantic Versions from Git history is often a sensible approach to versioning artifacts. It is also made incredibly easy thanks to tools such as GitVersion and semantic-release.
Power Apps solutions have some unique challenges when applying this approach:
Multiple solutions often need to be versioned independently within the same repository
Solution versions do not conform fully to the Semantic Versions specification
PowerVersion is designed to address these challenges and provide similar functionality to the tools mentioned above.
Prerequisites
You must have a solution project created with the Power App CLI
Your solution project must exist within a Git repository
Your Git workflow must be similar to Microsoft's Release flow
Simply build the solution project and the outputted solution's version will be set by PowerVersion based on the Git history.
Version increments
This section describes the different mechanisms in place to increment the solution version for a commit.
The starting version for the calculation is either the version in the Solution.xml (if no version tag is found) or the version in the latest version tag. It is recommended to set the version in the Solution.xml to 0.0.0 to ensure that all versioning is handled by PowerVersion - if have an existing solution project, create a version tag to ensure version calculation is started at the correct version.
Metadata commits
Metadata commits are commits that make updates under the solution metadata directory. By default, this is the src folder in the project created by the Power Apps CLI with pac solution init.
These commits will automatically increment the solution version. The kind of increment depends on the commit message title and is based on Conventional Commits:
A commit message with an ! after the Conventional Commits type is a major increment (refactor!: delete obsolete components)
A commit message with a Conventional Commits type of feat is a minor increment (feat: create an application)
A commit message containing anything else is a patch increment (fix: contact form script error)
Non-metadata commits
Non-metadata commits are commits that don't make any changes under the solution metadata directory but do update files that are mapped into the solution at build-time with the Solution Packager. Typically, these will relate to code components such as web resources and plug-in assemblies.
These kinds of commits do not automatically increment the solution version as it is not possible to determine which solutions have been updated. You must explicitly bump the solution manually using the following in the commit message body:
+semver(<solution-unique-name>): <increment>
An <increment> of major or breaking is a major increment
An <increment> of minor or feature is a minor increment
An <increment> of patch or fix is a patch increment
An explicit version increment of this type will take precedence if the same commit also increments the version as a metadata commit.
Version tags
It's possible to override the version calculated for a given commit using a Git tag:
<solution-unique-name>/#.#.#
The version calculation will start at the most recent version tag for the solution (or the first commit if no tags are found). It is recommended to periodically create a version tag to improve the performance of the version calculation.
Branch types
The version calculation differs based on the branch type.
Configuration
There are two MSBuild properties that can be set to configure how the branch type is determined for a given branch.
The mainline branch is master by default but this is configurable with the MainlineBranch MSBuild property.
The version of the mainline branch is calculated by determining the type of increment for each commit and applying each increment in order.
Release branches
A release branch is any branch that is prefixed by release/ by default but this is configurable with the ReleaseBranchPrefix MSBuild property.
The version is calculated by taking the mainline version (for the commit the release branch is based on) and setting the revision part of the version to the total number of commits on the release branch that increment the solution version. Only release branches generate a revision version (e.g. #.#.#.# rather than #.#.#) and this avoids hotfix versions clashing with mainline versions.
Topic branches
A topic branch is a branch that is neither the mainline branch nor does it match the release branch prefix.
The version of a feature branch is calculated by taking the mainline version (for the commit the feature branch is based on) and incrementing this by the highest increment found on the feature branch.
