Skip to content

Release Process

Jump to bottom
Wil Wade edited this page Mar 27, 2023 · 55 revisions

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

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...main
  • Ensure PRs with major changes have change/major label assigned to them

2. Cut New Release

  1. When code in main is ready to be released, a new release branch version tag must be created if the changes contain a runtime upgrade. This release branch version tag needs to have a semantic version in its name and will have the build with official Polkadot release.

    # 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

    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

    Examples of the release branches:

    • release-v1.0.1 - patch release over v1.0.0.
      • Small change that does not update the spec version
    • release-v1.2.0 - minor release over 1.1.X.
      • Updates the spec version or other medium change
    • release-v2.0.0 - major release over 1.X.X.
      • Breaking changes or other major changes to Frequency

    ❗ Pushing commits to a release branch will not automatically publish a new release. To trigger a release see step 4.

  2. Update the toml versions to match the release.

    • Replace X.X.X with the correct version: make version v=X.X.X
    • Commit the changed Cargo.toml and Cargo.lock files: git add Cargo.lock "**/Cargo.toml" && git commit -a -m "vX.X.X"
    • Push the new changes up to GitHub: git add. git commit -m "v-X.X.X" git push
    • Create new draft PR into main from release-vX.X.X

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

  3. Trigger running benchmarks in Jenkins to ensure we always have a final benchmark run and no local benchmarks slipped through. See Benchmarking Wiki for more info.

  4. Create a vX.X.X release tag and push it to remote. The deployer is responsible for creating a proper versioned release tag, no duplicate tags are allowed. Pushing release tag to remote will trigger a new release workflow run in GitHub CI.
    Examples of release tags:

    • v1.0.1-rc1 - release candidate for v1.0.1
    • v1.0.1 - full release

  5. Wait for the “Release” CI workflow run to finish. It will create a new GitHub release with all artifacts. The changelog in release notes is automatically generated against the full release tagged with the latest 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.

  6. Upon successful CI run completion, edit the GitHub release page, if needed.

  7. Once the release assets have been published in GitHub release, the frequency CI should dispatch "Auto Sign" workflow in metadata portal repo.

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

  9. Notify core team to start the upgrade runtime deployment process for Frequency Rococo and Frequency Mainnet: Upgrading Runtime Process

❗ When a release is triggered on a given release branch 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 git tag to the previous full release:

git fetch -tp
git checkout $PREVIOUS_FULL_RELEASE
git tag -a latest -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.

Clone this wiki locally