Creating a New Release

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 actually three levels of detail available when tracking what a release includes:

1. The Release Notes give the highest level view, suitable for most users.
2. The Milestone on GitHub may include some kinds of items (e.g. refactoring), which are not shown in the release notes.
3. The history of commits shows the most detailed and definitive view of what is in the code.

Checking the Milestone

Some issues will have been assigned a milestone upon creation, while others will only get one at the point the work is complete. 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

1. Make sure the milestone exists.
2. 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

2. Examine all closed issues and PRs since the last release. Decide which items should be in the milestone and add them if necessary.
3. Review the labels on all closed issues. (See the following section)
4. Transfer any remaining open issues to the next milestone.

Required Labels

We maintain two lists of labels for use in generating release notes. Every closed issue in the milestone must have a label from either the "Included" list or the "Excluded" list. An issue without one of these labels results in a failure in the build script.

Included Labels

Issues with these labels are listed in the release notes.

• Breaking Change
• Feature
• Enhancement
• Bug
• Documentation
• Build

Excluded Labels

Issues with these labels are excluded from the release notes even though they appear in the milestone.

• Refactor

Draft Release

We use a release branch to isolate the process of creating the release from our normal work. However, as currently designed, the process requires that main remain unchanged from the time the release branch is created up to the publishing of the new release. This is something we will want to change in the future.

1. Make sure your local master is up to date by pulling it.
2. Based on master, create a new local branch named "release-{milestone}", e.g. release-3.15.0.
3. Push the new branch, for example: git push -u origin release-1.5.0. Make sure the CI builds all pass.
4. The AppVeyor build creates a draft release on GitHub. Check it to see that all closed issues appear and that the text is correct. Edit and repeat as necessary until it is.

Production Release

Once the Draft Release is correct, continue here

5. Create a PR for the release branch and wait for the CI build to complete.
6. Merge the PR into master. This will trigger another build. Wait for it to complete.

Note: If you made any changes due to errors in the earlier steps, they are now in master.

7. Go to the draft release on GitHub and click Publish. This tags the release on master and triggers a final production build.
8. The production build uploads all packages to NuGet and Chocolatey and adds them as assets on the GitHub release. The milestone is closed and all the issues have comments added indicating the release in which they were resolved.
9. Update the Release Notes on the website.
10. Notify users of the new release.

Recovery from Errors

Step 8 above can be a particular source of problems. API keys may expire, for example, or communication problems may occur. 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.

In order to facilitate recovery, you may run some of the release targets 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
• PublishToMyGet

Limitations

1. The Release Notes on the website must currently be updated manually.
2. User notification is currently manual.
3. The process includes a large number of builds and much waiting. Some of those builds could be removed.