Release Guide

Note: this article is new, and only fully covers creating the initial release from a release-branch. Patch-releases are so far left as an exercise for the reader.

1. Create the release-branch

Find a good branch-out point, and create a release-branch. The branch-out point is usually going to be the tip of master, unless there's some other important concern for this release. The branch should be called something like release-X.Y, where X and Y are the major and minor release versions.

We don't make release-branches for patch-releases, we just keep developing on top of the respective minor-release branch.

Make sure all previous release-branches has been merged to this release-branch before proceeding.

2. Clean up CHANGELOG.md

Have a look over the top-most heading CHANGELOG.md to see that there's no obvious errors going on. Fix and commit any mistakes.

Make sure the top heading is the current release-version.

3. Update version number

The next thing we need to do, is to update the version number. The version number is stored in VERSION.txt.

We use release-candidates, where we postfix the version-number with -rcN (where N is the release candidate number, starting at 1), so the version number will be X.Y.0-rc1 for the first release on a new branch.

We normally do not use release-candidates for patch-releases. Changes in patch-releases should be small enough to be relatively risk-free, so we should be able to release these directly without involving QA-work.

To update the version number, simply edit the VERSION.txt-file. For example, you could do echo "1.2.0-rc1" > VERSION.txt for the release-1.2 branch. Commit the result.

4. Build packages

Building Uno's NuPkg and UPK packages are a matter of doing:

bash -l scripts/pack.sh

5. Publish the result

5.1. Release branch

Tag the tip of the branch, with a tag-name based on the version number, like so: vX.Y.Z. Include any release-candidate information in the tag name. So, the tag for the first release candidate for the 1.2 release-branch, should be called v1.2-rc1.

Push out the resulting branch and tag to the upstream repo, and mark the branch as "protected" on GitHub.

5.1.1. Protecting the release-branch

Go to "Settings" -> "Branches" -> "Choose a branch", and pick the newly created release-branch.

Use the following settings:

• Check Protect this branch
  • Check Require pull request reviews before merging
  • Check Require status checks to pass before merging
    • Check continuous-integration/appveyor/pr
    • Check continuous-integration/travis-ci
  • Check Restrict who can push to this branch

The result should look something like this:

5.1.2. Merge back to master

Merge the result back to the master-branch.

Make sure that there's an Unreleased-header in CHANGELOG.md.

5.2. Upload packages

We upload our packages to our MyGet stream. In order to upload there, you need to have an API-key. The scripts below will assume you have such a key, in the $KEY environment variable. You can of course also just replace $KEY with the actual key when invoking the commands instead if you want.

5.2.1 NuPkg packages

Upload all NuPkg-packages using NuGet:

for f in upload/*.nupkg; do nuget push -Source https://www.myget.org/F/fuse/api/v2/package -ApiKey $KEY $f; done

5.2.2 UPK packages

Uno itself has the ability to upload its pacakges to myget.org.

bin/uno push upload/*.upk --server https://www.myget.org/F/fuse/api/v2/package --key $KEY --out uno.packages

This produces an uno.packages-file, that should be uploaded to GitHub releases page for the release-tag.

Checklist

Here's a checklist that can be used to make sure everything has been done:

• Verify all previous release-branch has been merged.
• Verify that CHANGELOG.md is OK.
• If this is a minor-release (does not apply to patch-releases):
  • Create release-branch.
  • Protect release-branch.
• Update version number.
• Upload packages:
  • upload/FuseOpen.Uno.*.nupkg
  • upload/Uno.*.upk
  • upload uno.packages to the GitHub releases
• Merge to master.