Creating a New Release - nunit/nunit-console GitHub Wiki

Note: _Our release process is still under development. This page reflects the current status of the scripts as of release 3.13.1.

This page describes how we create a release, starting at the point where all issues to be included in the release, have been closed and the code merged to master. The current code in master serves as the basis for the release.

Creating a release includes publishing all our packages and creating release notes so that users can see what is included in each release. There are three separate stages to the process we follow...

Preparing the Release Milestone

Each of our releases is based on a milestone named for the release version. For example, milestone 3.14.0 would be used to produce a release of version 3.14.0 of the console runner and engine. Some issues will have been assigned a milestone upon creation, while others will only get one after the work is complete. To begin the release process, we must make sure that the milestone exists and contains the issues we want to see in the release notes.

Our current practice is to name the milestone according to the release version... 3.14.0, 3.15.0-beta1, etc. In order to begin the release process, the milestone must exist and contain all the completed work items we want to include in the release notes.

Steps to Take

  1. Make sure that a milestone exists with the correct name.

Note: This will always be a version number with three components, like 3.14.0, optionally followed by a hyphen and pre-release label, like 3.15.0-beta1.

  1. Edit the descriptive text of the milestone, which is used in generating the release notes.

Note: Currently, it's necessary to add a blank line before the descriptive text, due to a bug in GitReleaseManager

  1. Examine all closed issues and PRs since the last release. Decide which items should be in the milestone and add them if necessary.
  2. Review the labels on all closed issues. (See the following section)
  3. Remove any remaining open issues the milestone. If you know the milestone where they belong, assign them to that milestone. Otherwise, leave them without an assigned milestone.

Required Labels

Every issue in the milestone must contain one of the following labels: Breaking Change. Feature, Enhancement, Bug, Documentation, Build or Refactor. An issue without one of these labels causes a failure in the build script.

Issues with the Refactor label are excluded from the release notes even though they appear in the milestone. All the other issues are listed in the release notes under the heading of the label.

Additional labels such as those for priority are ignored in creating the release notes.

Creating the Draft Release

Once the milestone is set up as you want it, change into the root directory of the project on your development machine. Issue one of the following commands:

build --target=CreateDraftRelease --productVersion=VERSION` (Windows)
./build.sh --target=CreateDraftRelease --productVersion=VERSION` (Linux).

where VERSION is the release version as well as the name of the milestone.

A draft release will be created on GitHub. You should examine the draft in the browser to check that it looks correct. You may modify the milestone and re-run the command as many times as needed.

Note: In order to successfully run CreateDraftRelease, you must have the GITHUB_ACCESS_TOKEN environment variable set to the value of your own GitHub access token.

Note: If you are creating a version 3.x release, be sure to change the branch on which the release will occur from master to version3.

Releasing to Production

Before releasing to production, you should check that no additional work has been merged to master. If it has, you may need to modify the milestone and/or re-create the draft release.

To do the release, use your browser to navigate to the draft release on GitHub and click Publish. This tags the release on master and triggers a final production build. That build creates and uploads all packages to both NuGet and Chocolatey and adds them as assets on the GitHub release. The milestone is closed and comments are added to all the closed issues, indicating the release in which they were resolved.

At this point, you should manually update the Release Notes on the website and notify users of the new release. (These steps may be automated in the future.)

Recovery from Errors

Errors can arise when releasing to production. The most common causes are communication failures and expiration of API keys. The publication of packages is set up so that it continues after any error, uploading what it can. For example, publishing to NuGet may succeed while all Chocolatey uploads fail. It's even possible for some uploads to a particular service fail, while others succeed.

You can see if a release has failed by looking at the assets. If you have only source files there, then the packages have not been uploaded.

In order to facilitate recovery, you may run some of the release targets directly on your local machine, provided you have the access keys. Before running anything, you should switch to your local copy of master, pull the latest changes and run build --target=Package. Once that's done, you may run any of the following targets.

  • PublishToMyGet
  • PublishToNuGet
  • PublishToChocolatey
  • CreateDraftRelease
  • CreateProductionRelease

Note: If you release from another branch than master, tag the branch you're in with the release number you want (e.g.3.15.5) and run build --target=Package again.
Then run CreateProductionRelease, this will add the missing packages to the release. And then run PublishToNuGet.

Note 2: To publish to Chocolatey, you need to be a manager of the packages, and you need to set the CHOCO_API_KEY to the value you have generated on the Chocolatey site which you find under your Account.

See Error Recovery Example for an illustrative example of how this is done.