In order to best understand the use case for GitReleaseManager let's take a look at an example workflow currently in use by the ChocolateyGUI project.
ChocolateyGUI uses a number of concepts, for example, GitFlow, psake build script engine, AppVeyor Continuous Integration, as well as using GitReleaseManager. In order to understand the usage of GitReleaseManager for this project, you sort of have to understand the entire process. As a result, this walk-through steps you through the entire end to end process, which as a result, means it is quite lengthy.
ChocolateyGUI is an open source project, hosted on GitHub that makes use of GitReleaseManager to create and export it's release notes. Before we can get into how GitReleaseManager is used, we need to take a look at how ChocolateyGUI is setup.
- All Issues are tracked using the GitHub Issues List
- Each Issue is assigned to a project milestone
- Each Issue is appropriately tagged using one of the pre-defined labels
- ChocolateyGUI uses the GitFlow Branching Model
- GitVersion is used to determine the current version number, based on the current state of the repository, i.e. what branch is being worked on, and what tags have been assigned, and how many commits have been made to the repository
Every build of ChocolateyGUI generates a number of Build Artifacts, these include: * An MSI package for installing ChocolateyGUI * A Chocolatey package to ease the installation of ChocolateyGUI
- ChocolateyGUI uses AppVeyor as it's Continuous Integration Server.
- Any time a Pull Request is created, an AppVeyor build is triggered, but no deployment of the build artifacts takes place
- Any time a commit is made into the develop branch, an AppVeyor build is triggered, and the build artifacts are deployed to the MyGet Develop Feed
- Any time a commit is made into the master branch, an AppVeyor build is triggered, and the build artifacts are deployed to the MyGet Master Feed
- Any time a tag is applied to the repository, an AppVeyor build is triggered, and the build artifacts are deployed to Chocolatey.org for public consumption.
Ok, so where does GitReleaseManager come into play?
The role of GitReleaseManager really comes into play when moving between a release or hotfix branch and the master branch.
Let's say you have done a bunch of work on the develop branch, you want to move all of that work into the master branch, via a release branch. When you do this, you are effectively saying that the milestone that you were working on is almost ready for release. It is at this point that you should really know, via the issues list, everything that is being included in the release, and now would seem like a great time to create some release notes. And this is exactly what the build process for ChocolateyGUI does. Let's break this down further...
- A release branch is created from develop branch
- The release branch is merged into master branch, triggering a build (with deployment to MyGet Master Feed).
- During this build, GitReleaseManager is executed, using the create command, and the version number which was provided by GitVersion, to create a set of release notes for this milestone - source.
- This set of release notes is created in draft format, ready for review, in the GitHub UI.
- The build artifacts which have been deployed to MyGet Master Feed are tested
- The release notes are reviewed, and ensured to be correct
- Assuming that everything is verified to be correct, the draft release is then published through the GitHub UI, which creates a tag in the repository, triggering another AppVeyor build, this time with deployment to Chocolatey.org
- During this build, GitReleaseManager is executed using the export command, so that all release notes can be bundled into the application - source
- In addition, GitReleaseManager is executed using the addasset command to add the build artifacts to the GitHub release - source
- And finally, GitReleaseManager is executed using the close command to close the milestone associated with the release that has just been published - source
The end result of this process can be seen here. This release included 218 commits, and 75 issues. Personally, I simply wouldn't have created such a comprehensive set of release notes manually. Instead, I would have written something like...
#0.12.0 This release included lots of bug fixes, and tonnes of new features. Enjoy!
By leveraging GitVersion, and GitReleaseManager, and a small amount of process (which you are likely already doing), I hope you will agree that you can very easily create a comprehensive set of release notes for your application.