Skip to content

Frequency Git Workflow

Jump to bottom
Dmitri edited this page Dec 8, 2022 · 30 revisions

Overview

Frequency Multi-Branch Git Workflow

Source Diagram: https://docs.google.com/drawings/d/1GyvodIcZ3AfrfmpgK465N369Lu-F41Ni-__Gvk4p6iQ

This page describes Git branching workflow employed by the Frequency team during development and release cycles. This workflow has 4 types of branches:

Number Branch Name Type Branch Pattern Purpose
1 Developer Branch Short-Lived [issue#]-[brief-descriptive-name] a.k.a "feature branch", used to develop new features and make other changes for the upcoming releases.
2 Release Branch Long-Lived release-v[x.x.x*] Frequency release tied to the specific Polkadot release version, etc., e.g. release-v0.9.29, release-v0.9.30, release-v0.9.30-1, etc.
3 Next Branch Long-Lived origin/main Represents the next version under development, i.e. a release candidate.
4 Hot Fix Branch Short-Lived [issue#]-[brief-descriptive-name] These hot fix branches are necessary to act immediately upon an undesired status of one of the current releases (Rococo and/or Mainnet).

Once a long-lived branch is created, it can stay in the repo forever. In other words, there is no time limitation on the lifecycle of such branch.

Change Management

To work on something new:

  1. Create a new developer branch off main and give it a descriptive name starting with the story number (ie: 504-retire-msa-id, , 323-upgrade-runtime-v0.29.0, etc.) if there is a GitHub story associated with this change. Direct commits to main` are not allowed.
  2. Commit to that branch locally and regularly push your work to the same named branch on the server.
  3. Run tests locally.
  4. When you need feedback or help, or you think the branch is ready for merging, open a pull request. This will trigger "Verify PR" CI workflow which will execute multiple checks on the code changes in the PR.
  5. If CI fails, address reported issues and push a new commit to remote. This will trigger a new "Verify PR" workflow run. Repeat this step until all jobs in CI are passing successfully.
  6. After someone else has reviewed and signed off on the feature, you can merge your PR into main.

Releases

When code in main is ready to be released a new release branch must be created if the changes contain a runtime upgrade. This release branch needs to have a version in its name tied to the official Polkadot release.

Examples of the release branches:

  • release-v0.29.0 - release branch which was upgraded to Polkadot v0.29.0 runtime.
  • release-v0.30.0 - release branch which was upgraded to Polkadot v0.30.0 runtime.

Pushing commits to a release branch will not automatically publish a new release. To trigger a release, a deployer needs to tag a given commit with the vx.x.x* release tag and push it to the remote. This will trigger the "release" CI workflow.

Examples of the release tags:

  • v0.9.29-rc1 - release candidate corresponding to Polkadot v0.9.29 runtime
  • v0.9.29 - full release corresponding to Polkadot v0.9.29 runtime
  • v0.9.29-1 - additional change 1 to the existing v0.9.29 Frequency full release
  • v0.9.29-2 - additional change 2 to the existing v0.9.29 Frequency full release
  • v0.9.30 - corresponds to Polkadot full release v0.9.30

Basically, the release process consists of these steps:

  1. Create a v*.*.* release tag and push it to remote. The deployer is responsible for creating a proper versioned release tag. No duplicate tags are allowed. 
    # This will triggers new release workflow run in GitHub CI
git tag -a v0.9.30 -m "New v0.9.30 release" && git push origin --tags
  2. Wait for the “Release” CI workflow run to finish. It will create a new GitHub release with all artifacts. The change log in release notes is automatically generated against the full release tagged with the latest tag. The latest tag is moved between full releases only, thus the changelog in a release candidate will always be generated against the latest full release.
  3. Upon successful CI run completion, edit the GitHub release page, if needed.

When a release is triggered on a given release branch, 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. The PR titles are sanitized to remove special chars as backticks, square brackets, etc.

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