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. Update Uno

Stuff/packages.config contains the reference to FuseOpen.Uno.Tool, which is the package for the uno binary. You need to update the version number there to the version of Uno the release should contain.

In addition, we need to overwrite stuff/uno.packages with the file from the corresponding release at the GitHub Releases page for Uno.

3. Update CHANGELOG.md

All markdown-files in the CHANGELOG/ directory should be pasted into CHANGELOG.md and formatted as appropriate. Delete the markdown-files after this is done.

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.

4. 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.

5. Build packages

Building the UPK packages are a matter of doing:

bash build.sh
bash pack.sh

6. Publish the result

6.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.

6.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:

6.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.

6.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.

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

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

This produces an fuselibs.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.
• Update Uno
• Update CHANGELOG.md
• If this is a minor-release (does not apply to patch-releases):
  • Create release-branch.
  • Protect release-branch.
• Update version number.
• Upload packages:
  • UPK packages
  • upload fuselibs.packages to the GitHub releases
• Merge to master.