Skip to content

Release Process

Jump to bottom
Wil Wade edited this page Oct 20, 2023 · 54 revisions

💡 Please make sure to get to know the Frequency Git Workflow Process first.

Normal Release Process Overview

  • Pull requests are made and merged into the main branch of the Frequency Git repository
  • As needed, releases are made off of the main branch. These might be release candidates or full releases
    • These releases are manually triggered, but then follow than automated process below to perform the release
    • Complete benchmarks are run
    • Many tests and validations are made
    • New release of the NPM package @frequencychain/api-augment is created
    • New releases of the various Docker images are released to Docker Hub
    • A GitHub Release is created with a generated Changelog
  • The GitHub Release is then edited for greater readability and higher visibility of breaking changes
  • Some Testnet nodes will be upgraded
  • After 1-5 days, the release is pushed to the Frequency Testnet on the Rococo Relay chain
  • The Integration tests are run against Testnet
  • Any issues found or reported may mean that the process starts over
  • After 7-14 days post Testnet upgrade the process to upgrade the runtime on Mainnet begins

Core Concepts

  • Release branch is a branch that only accepts commits accepted to stabilize a version of the product ready for release
  • Release branch will copy from the current mainline, but not allow any new features to added to it
  • The developers working on the release focus solely on removing any defects that stop the release from being production-ready. Any fixes to these defects are created on the release branch and merged to mainline. Once there are no more faults to deal with, the branch is ready for production release.
  • A problem with applying the commits to the release branch in this way is that it's too easy to neglect to copy them over to the mainline, particularly as it gets harder due to divergence. The resulting regression is very embarrassing. Consequently some people favor creating the commits on mainline, and only once they are working there to cherry-pick them into the release branch.

Create New Release

1. Release Checklist

  • Review diffs with the previous release: _LATEST-FULL-RELEASE...main
  • Ensure PRs with major changes have change/major label assigned to them

2. Cut New Release

Examples of the release version tags:

  • v1.0.1 - patch release over v1.0.0.
    • Small change that does not update the spec version
  • v1.2.0 - minor release over 1.1.X.
    • Updates the spec version or other medium change
  • v1.3.0-rc1 - release candidate 1 in preparation for the new full release 1.3.0.
  • v2.0.0 - major release over 1.X.X.
    • Breaking changes or other major changes to Frequency

When code in main is ready to be released:

OPTION 1: Manually via GitHub UI

  1. Go to Release workflow page
  2. Click on [Run workflow] button, enter new release version and click on green [Run Workflow] button.
    Screenshot 2023-04-05 at 7 37 01 PM

OPTION 2: Via Pushing Git Tag

A new release version tag must be created and pushed to remote if the changes contain a runtime upgrade. This release version tag needs to have a semantic version in its name.

# A) Brand new release tag
export tag=v1.2.0; git tag -a $tag -m "New $tag release" && git push origin $tag

# B) Use -f option if you need to override an existing tag locally and on remote
export tag=v1.2.0; git tag -a $tag -m "New $tag release" -f && git push origin $tag -f

# To delete some stale tag locally and on remote you may find this command helpful
export tag=v1.0.1-rc5; git tag -d $tag; git push origin :$tag

This will kick off a new Release workflow run in CI.

Let CI Do the Work

  1. Wait for the “Release” CI workflow run to finish. It will create a new GitHub release with all artifacts. The changelog in the release notes is automatically generated against the full release tagged with the _LATEST-FULL-RELEASE git tag. This tag is moved between full releases only, thus the changelog in a release candidate will always be generated against the latest full release. The PR titles are sanitized to remove special chars as backticks, square brackets, etc. ❗ The Cargo.toml files will have the Polkadot version appended as build information. e.g. v1.1.0+polkadot0.9.32 is v1.1.0 of Frequency which was built on the Polkadot v0.9.32 release.
  2. Upon successful CI run completion, edit the GitHub release page, if needed.
  3. Once the release assets have been published in GitHub release, the frequency CI should dispatch "Auto Sign" workflow in metadata portal repo.
  4. Upon completion of "Auto Sign" workflow run, check metadata-portal repo for a new PR with updated metadata QR image file(s). This PR should contain one or more QR code images with a .apng|.png extension. Merge this PR and it will deploy these updated QR image(s) to https://metadata.frequency.xyz website.
  5. Notify core team to start the upgrade runtime deployment process for Frequency Rococo and Frequency Mainnet: Upgrading Runtime Process

❗ When a release is triggered with a given release version tag, all artifacts for all networks will be built and published. This gives the node owner a flexible choice to use any artifact from any published release version.

Roll Out New Release

Follow instructions on Upgrading Runtime

Rollback Release

Let's assume we are rolling back the latest full release v1.2.0 to the previous full release v1.1.0

export ROLLBACK_RELEASE_FROM=v1.2.0;
export ROLLBACK_RELEASE_TO=v1.1.0;
export PREVIOUS_FULL_RELEASE=v1.1.0;

1. GitHub Release Page:

  • Delete $ROLLBACK_RELEASE_FROM release from GitHub Releases page
  • Mark the previous GitHub release $ROLLBACK_RELEASE_TO as latest

2. If rolling back a full release, move the _LATEST-FULL-RELEASE git tag to the previous full release:

git fetch -tp
git checkout $PREVIOUS_FULL_RELEASE
git tag -a _LATEST-FULL-RELEASE -m "Tag previous full release as latest" -f && git push origin --tags -f

3. Frequency DockerHub Repositories:

  • Log in to DockerHub with admin user (e.g. [email protected])
  • Delete $ROLLBACK_RELEASE_FROM release tags in each published image on DockerHub
  • Tag the previous full release images with the latest tag in DockerHub. Assuming we want to tag $ROLLBACK_RELEASE_TO release as the latest: 
    docker login -u frequencychain
---
Password: <password>
    export tag=$ROLLBACK_RELEASE_TO; # e.g. v1.3.0
export docker_repo=frequencychain/instant-seal-node && \
 docker pull $docker_repo:$tag --platform linux/x86_64/v8 && \
 docker tag $docker_repo:$tag $docker_repo:latest && \
 docker push $docker_repo:latest;
export docker_repo=frequencychain/collator-node-local && \
 docker pull $docker_repo:$tag --platform linux/x86_64/v8 && \
 docker tag $docker_repo:$tag $docker_repo:latest && \
 docker push $docker_repo:latest;
export docker_repo=frequencychain/parachain-node-rococo && \
 docker pull $docker_repo:$tag --platform linux/x86_64/v8 && \
 docker tag $docker_repo:$tag $docker_repo:latest && \
 docker push $docker_repo:latest;
export docker_repo=frequencychain/parachain-node-mainnet && \
 docker pull $docker_repo:$tag --platform linux/x86_64/v8 && \
 docker tag $docker_repo:$tag $docker_repo:latest && \
 docker push $docker_repo:latest;

4. NPM:

❗ Unfortunately a version published on NPM cannot be completely rolled back.

  • Deprecate the old version (Requires write permission to @frequency-chain/api-augment and npm login)

    npm deprecate @frequency-chain/api-augment@$ROLLBACK_RELEASE_FROM "Rolling back to $ROLLBACK_RELEASE_TO"

Hot Fixes

Hot fixes are used to quickly patch production releases. These fixes can be made directly to a release branch via a PR. The developer is responsible for porting hot fixes back to main and whatever other release branch those changes may be applicable to.

Create Test Release

A test release is used for testing the GitHub Actions release workflow. Please note that some workflow steps (e.g. uploading artifacts to NPM, dispatching auto-signer workflow) are skipped during test run with if: env.TEST_RUN != 'true' condition.

1. Trigger Test Release

A test release has the following reserved release tags:

  • Release candidate: a release tag matching v0.0.1-rc[0-9]+ (e.g. v0.0.1-rc1, v0.0.1-rc2, etc.)
  • Full release: v0.0.1 release tag

A test release can be triggered either from GitHub Release Workflow UI or from a command line with:

  • To trigger a test release candidate: 
    # Clean any leftovers from the previous test release candidate run
$ export ver=v0.0.1-rc1; git push origin :release-$ver; git tag -d $ver; git push origin :$ver
# Push release tag to remote to trigger test release
$ git tag -a $ver -m "Test release for #<issue_number>" -f && git push origin --tags -f
  • To trigger a full test release: 
    # Clean any leftovers from the previous full test release run
$ export ver=v0.0.1; git push origin :release-$ver; git tag -d $ver; git push origin :$ver
# Push release tag to remote to trigger test release
$ git tag -a $ver -m "Test release for #<issue_number>" -f && git push origin --tags -f

❗ DO NOT forget to clean up after a test workflow run. See the next section below.

2. Clean Up After Test Release

Follow these steps to clean up after cutting a test release:

  1. Remove the branch and the tag, created during a test release run, with this shell command. Just set ver env var to the test release version you are trying to clean up after: 
    # Clean up after Release Candidate
export ver=v0.0.1-rc1; git push origin :release-$ver; git tag -d $ver; git push origin :$ver
# Clean up after rFull Release
export ver=v0.0.1; git push origin :release-$ver; git tag -d $ver; git push origin :$ver
  2. Delete published test release from the Frequency GitHub Releases Page
Clone this wiki locally