The easy way to use semantic versioning (semver.org) with a GitHub Flow or trunk/mainline development Git workflow.
It supports using any Git repository as long as you are using master and furthermore, it supports detection and versioning of Pull Requests if you are using GitHub or Stash.
GitHubFlowVersion will automatically version your application to SemVer of {vLast.Major}.{vLast.Minor}.{vLast.Patch+1} where vLast is the last Git Tag in your repo.
This means your versions are based on source control metadata making it repeatable. GitHubFlowVersion gives you flexibility by making variables available to your build so you can meet all your versioning requirements. See Available Variables for the full list of variables
It also means that unlike many other versioning strategies you do not have to rebuild your project to bump the version!
There are two ways to use GitHubFlowVersion
Simply call GitHubFlowVersion.exe [/UpdateAssemblyInfo] as the first step in your TeamCity build process
This will set the TeamCity build number to {vLast.Major}.{vLast.Minor}.{vLast.Patch+1}+{###} (by setting the %build.number% variable). For example if the last tag was 1.2.0 then TeamCity's build number will be 1.2.1+005 (where 5 is the number of commits since the last tag). Read more about the Versioning Conventions
The Available Variables for the full list of variables will become TeamCity system. variables for you to pass/use in the rest of your build process
To make all the variables available, GitHubFlowVersion has to call your build scripts. We support MSBuild or any arbitrary executable (including non-.NET applications) via the ProjectFile and Exec commandline options respectively:
GitHubFlowVersion.exe /ProjectFile MyMSBuildProject.proj /Targets Build;Package [/UpdateAssemblyInfo]
or
GitHubFlowVersion.exe /Exec rake.exe /ExecArgs "scripts/build" [/UpdateAssemblyInfo]
GitHubFlowVersion.exe does this to version itself, See GitHubFlowVersion's Build Script for examples on how it can be used in an MSBuild file and
To bump the SemVer of your project, simple add/edit the NextVersion.txt file and put the next SemVer into it. GitHubFlowVersion will use the version in NextVersion.txt over the convention if it is higher than the convention version. Which means when you tag your release, then your patch will automatically be bumped for the next build and the build metadata will reset to 000.
You can install it from NuGet or download the compiled executable from the Latest Release on GitHub.
Installing from NuGet will copy itself into $(SolutionDir)\tools\GitHubFlowVersion, this gives you a fixed path to run GitHubFlowVersion from which is not affected by package restore.
Environmental variables can be set to process or user scoped (which is not an option for us), if you build script calls GitHubFlowVersion it will run then exit, and the variables it sets will not be avaialble for your build
If you specify the /UpdateAssemblyInfo flag, then we will find all AssemblyInfo.cs files in your git repo and update the AssemblyVersion, AssemblyFileVersion and AssemblyInformationalVersion.
We will only update the version in attributes which exist, so if you want us to update the AssemblyInformationalVersion then simply add that attribute into your AssemblyInfo.cs and it will be updated.
If you ran GitHubFlowVersion with the /Exec or the /ProjectFile parameters we will automatically revert the changes we made to your AssemblyInfo.cs files after we have run your build.
It isn't that different, except it adds the following which makes the process work for Continuous Delivery and also generally reduces friction
- After a release is tagged, the patch will be bumped automatically
- Pull requests are labeled as -PullRequestXX, meaning they have a lower semantic version than
master - Non-master branches will be tagged with the branch name, making their semantic version lower, for example a branch named
betawill have a SemVer of1.2.1-beta+000 - Each pull request can edit the
NextVersion.txtfile independently, and the CI builds which are produced will all be correct, theNextVersion.txtthen can be merged and you simply take the highest number
Conceptually it is also different, we are saying the next version to be released is #.#.#. Then all non-master builds are automatically pre-release making their version lower than master.
Read more at How GitHubFlowVersion works
What is the difference between GitFlowVersion and this?
This project is based on the idea's of GitFlowVersion except it is designed to work with GitHub Flow rather than GitFlow which is a much more complicated branching strategy
SemVer 2.0 allows you to specify build metadata, which does not affect the Semantic Version. For example 1.2.0+011 is the same Semantic Version as 1.2.0+100
We use this by default so CI builds consistently build the next releasable package
In a nutshell, they will simply follow the same conventions as master, except all builds will have a pre-release tag of -PullRequest for pull requests and -{branchname} for non-master branches. Read more at Pull Requests or Non-master branches
The idea and a bit of the code is from https://github.com/Particular/GitFlowVersion.
I decided not to fork because this project is a lot simpler. If you use GitFlow I highly suggest you check out GitFlowVersion, it is a really great idea.
This project was born because I prefer GitHub Flow over GitFlow for my open source projects.
Feedback, contributions, bug reports and questions are more than welcome, please raise issues/suggestions at: https://github.com/JakeGinnivan/GitHubFlowVersion/issues or contact Jake Ginnivan, Robert Moore or Matt Davies on Twitter.