Release Process

GDK for Unity Release Process

This document outlines the process for releasing a version of the GDK for Unity and any starter projects. Its important to note that releases do not have to happen in lockstep. Note that any of these releases may require a docs roll out.

This process will need to be reviewed once we hit beta.

Terminology

• Release version is the version of the SpatialOS GDK for Unity that you are releasing by performing the steps in this document.
• Previous version is the latest version of the SpatialOS GDK for Unity that is currently released to customers. You can find out what this version is here.
• Pre-alpha version: The SpatialOS GDK for Unity is currently in alpha, but some of our feature modules
  (such as the Mobile feature module) are still in pre-alpha. This is indicated by their version number, which will be formatted 0.0.x instead of 0.1.x, to indicate their pre-alpha state.

Pre-Validation

These steps are common to all repositories.

1. Call a freeze on merges to the develop branch in #dev-unity-internal.
2. Create a branch locally based from origin/develop called feature/release-<version>.
   • git checkout -b feature/release-<version> origin/develop
3. Check if the gdk.pinned file is present in the root of the repository. If it is, ask in #dev-unity-internal if the SpatialOS version and/or any core package references need to be updated.
4. Update the version field in every package.json file in the repository so that they the match the release version.
   • There is a package.json file in each of the com.improbable.* folders in gdk-for-unity/workers/unity/Packages.
   • You must also update the version of the packages referenced in the dependencies field in these files.
   • The version number of pre-alpha packages, such as Mobile, should be also be updated by, but they should remain in pre-alpha unless they have met our criteria for alpha.
5. Open CHANGELOG.md, which is in the root of the repository, and put the release version and planned date of release in a ## block. Move the Unreleased section above this.
   • Look at the previous release versions in the changelog to see how this should be done.
6. Update the version field in packer.config.json, which is in the root of the repository, to the release version.
7. Make a commit, push, open a PR into develop.

Implementing fixes

If you're making a docs fix, replace feature/release-<version> with docs/improbadoc-conversion when executing the below steps.

If at any point in the below validation steps you encounter a blocker, you must fix that defect prior to releasing. The workflow for this is:

• Raise a bug ticket detailing the blocker.
• git checkout feature/release-<version> if you are not on the release branch already.
• git checkout -b bugfix/UTY-xxx
• Fix the defect.
• Make a commit, push, open a PR into feature/release-<version>.
• When this PR is merged, git checkout feature/release-<version> and re-test the defect to ensure you fixed it.
• Continue the validation steps from where you left off.

Validation (Core)

1. Download the SpatialOS GDK for Unity, checkout the feature/release-<version> branch that you created, and run the setup steps, including installing the mobile dependencies.
2. Ensure that each of the buttons in the SpatialOS toolbar behave as expected.
3. Run the Release QA pipeline in Buildkite.
   • This will launch a deployment.
4. Connect a Windows and MacOS client via the launcher to the deployment.
5. Connect a mobile client (both iOS and Android) with development authentication.

When the steps above have been executed, merge feature/release-<version> into develop.

Validation (FPS)

1. Launch a cloud deployment with the deployment launcher window found in: SpatialOS/Deployment Launcher.
   • Use cloud_launch_large.json and cloud_launch_large_sim_players.json for the configs.
2. Connect a Windows and MacOS client via the launcher to the deployment.
3. Connect a mobile client (both iOS and Android) with development authentication.

Validation (Blank)

1. Run the Release QA pipeline in Buildkite.
   • This will launch a deployment.
2. Connect a Windows and MacOS client via the launcher to the deployment.
3. Connect a mobile client (both iOS and Android) with development authentication.

Note that when you connect, nothing will appear on screen - in the Inspector however, there should be a Player entity.

Validation (Docs)

1. Upload docs to docs-testing using Improbadoc.
2. Validate that Improbadoc reports no broken links.
3. Scan through the setup and tutorial guides and ensure nothing is wrong or broken.

Pre-Release

1. Merge the PR from feature/release-<version> into develop.
2. Draft a release at the HEAD of develop from the Github Releases page.
3. Copy the release notes into the body.
4. Run ci/pack.sh in the repository and upload the *.zip file it creates.

Release

1. Rebase master against develop.
   • git checkout master && git rebase develop.
   • Make sure both branches are up to date before running this command. If you are unsure, please ask for help.
2. Push master.
   • Remove branch protection from the master.
   • Run git checkout master && git push -f origin
   • Note that this action is potentially destructive, be very sure before you do .
   • Add branch protection to the master branch.
3. Publish the release.
4. Publish the docs to live using Improbadoc
5. Publish a notice in the forums, on Discord (#unity channel), and in the #releases channel in Slack.

Appendix

Forum Post Template

We are happy to announce the release of version x.y.z of the SpatialOS GDK for Unity along with updated versions of our FPS Starter Project and Blank Starter Project.

Please see the detailed release notes on GitHub:

GDK for Unity - https://github.com/spatialos/gdk-for-unity/releases/tag/x.y.z
FPS Starter Project - https://github.com/spatialos/gdk-for-unity-fps-starter-project/releases/tag/x.y.z
Blank Starter Project - https://github.com/spatialos/gdk-for-unity-blank-project/releases/tag/x.y.z