Skip to content
This repository has been archived by the owner on Jan 18, 2022. It is now read-only.

Release Process

Jump to bottom
jessicafalk edited this page Jun 12, 2019 · 48 revisions

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. Ask if anyone @here knows of any blocking defects in code or docs that should be resolved prior to commencement of the release process.
  2. Create a branch locally based from origin/develop called feature/release-<version>.
    • git checkout -b feature/release-<version> origin/develop
  3. Update the version field in packer.config.json, which is in the root of the repository, to the release version.
  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. Make a commit, push, open a PR into develop.

Implementing fixes

If you're making a docs fix, replace origin/develop with docs-next 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 origin/develop 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 develop.
  • When this PR is merged: git checkout feature/release-<version>
  • Rebase the release branch on top of develop: git rebase origin develop
  • 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. Validate that all Deployment Launcher functionality works as expected.
  4. Run the Release QA pipeline in Buildkite.
    • This will launch a deployment.
  5. Connect a Windows and MacOS client via the launcher to the deployment.
  6. Connect a mobile client (both iOS and Android) with development authentication.
  7. Connect a Windows client to a local deployment.
  8. Connect a Mac client to a local deployment.
  9. Connect a mobile iOS client to a local deployment.
  10. Connect a mobile Android client to a local deployment.

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

  1. After feature/release-<version> has been merged into develop, we need to generate updated API documentation.
  2. To do this, run ./ci/generate-docs.sh <commit_hash> where <commit_hash> is the HEAD of develop.
    • If you have the Hub CLI setup - it should create a PR automatically.
    • If not, the branch will be pushed and you can manually create the PR.

Note that currently the API ToC cannot be included automatically in the main ToC so updating the ToC is still manual. After the branch is pushed, you'll need to check it out and copy the contents of docs/api/.toc/toc.md into the appropriate place in docs/toc.md.

Validation (FPS)

  1. Update the gdk.pinned file with the commit hash at the head of develop.
  2. Open the map builder window found in: SpatialOS/Map Builder.
    • Ensure that a 24 layer map generated with default map builder settings matches the navmesh in the FPS-Development and FPS-SimulatedPlayerCoordinator scenes.
  3. Launch a cloud deployment with the deployment launcher window found in: SpatialOS/Deployment Launcher.
    1. Ensure a cloud deployment launches successfully without modifying the default deployment configuration.
    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.
  4. Connect a Windows client to a local deployment.
  5. Connect a Mac client to a local deployment.
  6. Connect a mobile iOS client to a local deployment.
  7. Connect a mobile Android client to a local deployment.
  8. Enable session-based gameplay and start the deployment manager. Ensure that the deployment manager is able to spin up deployments and restarts them after the session ends.
  9. Start a Windows client and connect to one of the sessions. Ensure that all buttons work and display the list of sessions as expected
  10. Start a MacOS client and connect to one of the sessions
  11. Start an Android client and connect to one of the sessions
  12. Start an iOS client and connect to one of the sessions

Validation (Blank)

  1. Update the gdk.pinned file with the commit hash at the head of develop.
  2. Run the Release QA pipeline in Buildkite to launch a cloud deployment.
    1. Connect a Windows and MacOS client via the launcher to the deployment.
    2. Connect a mobile client (both iOS and Android) with development authentication.
  3. Connect a Windows client to a local deployment.
  4. Connect a Mac client to a local deployment.
  5. Connect a mobile iOS client to a local deployment.
  6. Connect a mobile Android client to a local deployment.

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.

Release

Core / FPS / Blank project

  1. Merge the PR from feature/release-<version> into develop.
  2. Rebase master against develop by running git checkout origin/master && git rebase origin/develop.
  3. Remove branch protection from the master.
  4. Run git checkout master && git push -f origin. Note that this action is potentially destructive, be very sure before you perform it.
  5. Re-add branch protection to the master branch.
  6. Using the Github Releases page, draft a release at the HEAD of master. Copy and paste the release notes from CHANGELOG.md.
  7. Run ci/pack.sh in the repository and upload the *.zip file it creates.
  8. Publish the release.
  9. Create issues for all new known issues in the different repos.
  10. Close resolved issues.
  11. Ensure the Known Issues board is up to date.

Documentation

  1. git checkout docs-next.
  2. Publish the docs to live using Improbadoc commands listed here.
    • You must perform improbadoc build before publishing docs.
  3. Verify the correct docs changes are live.
  4. Disable branch protection on docs-current
  5. Force push docs-next as the new docs-current
  6. Enable branch protection on docs-current

Announce release

  1. Draft an announcement on:
    • Forums
    • Discord (#unity channel)
    • Slack (#releases channel)
    • Email (spatialos-announce)
  2. Verify links in the draft announcement
  3. Verify that Core, FPS and Blank project releases have been successful
  4. Verify the docs release was successful
  5. Publish announcements

Appendix

Announcement Template

Hi all,

We've just released the GDK for Unity <version>, which contains <some description of what's in the new release>.

The full release notes can be found here: https://github.com/spatialos/gdk-for-unity/releases/tag/<version>

This release also contains updated versions of our FPS Starter Project and Blank Project:
• https://github.com/spatialos/gdk-for-unity-fps-starter-project/releases/tag/<version>
• https://github.com/spatialos/gdk-for-unity-blank-project/releases/tag/<version>

Cheers,
<your name here>
Clone this wiki locally