Frequency Git Workflow

Overview

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.29.0-rc1 - release candidate corresponding to Polkadot v0.29.0 runtime
• v0.29.0 - full release corresponding to Polkadot v0.29.0 runtime
• v0.29.0-1 - additional change 1 to the existing v0.29.0 Frequency full release
• v0.29.0-2 - additional change 2 to the existing v0.29.0 Frequency full release
• v0.30.0 - corresponds to Polkadot full release v0.30.0

Basically, the release process consists of these steps:

1. Create a v* release tag and push it to remote.
2. Wait for the “Release” CI workflow to finish and create a new GitHub release with artifacts.
3. Edit GitHub release page as 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 deployer is responsible for creating a proper versioned release tag. No duplicate tags are allowed.

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.