Tagging a release

October 10, 2025 ยท View on GitHub

New release branch setup

New major release branch

Pre-requisites for creating a release branch for a new major version:

  1. Bump Go package version.
  2. Change all imports. For example: if the next major version is v3, then change all imports starting with github.com/cosmos/ibc-go/v2 to github.com/cosmos/ibc-go/v3).

Once the above pre-requisites are satisfied:

  1. Start on main.
  2. Create the release branch (release/vX.XX.X). For example: release/v3.0.x.

New minor release branch

  1. Start on the latest release branch in the same major release line. For example: the latest release branch in the v3 release line is v3.2.x.
  2. Create branch from the release branch. For example: create branch release/v3.3.x from v3.2.x.

Post branch creation

Post-requisites for both new major and minor release branches:

  1. Add backport task to mergify.yml.
  2. Create label for backport (e.g.backport-to-v3.0.x).
  3. Add the branch to e2e-compatibility.yaml in the workflow_dispatch.inputs.release-branch.options list.

General release procedure

For specifics around point release procedure, see the documentation for that below.

NOTE: Since ibc-go v10, we release sub-modules (e.g. modules/light-clients/08-wasm/v10.3.0) from the same release branch as ibc-go.

0: Before release

  1. Before tagging a new release, make sure to run the compatibility e2e test suite for the corresponding release line.
  2. Make sure the CHANGELOG.md is updated.

1: Release ibc-go

  1. Create a new release in GitHub with "Draft new release".
  2. Select the release branch (e.g. release/v10.4.x)
  3. Set the correct tag (e.g. v10.4.0)
  4. Write release notes
  5. Check the This is a pre-release checkbox if needed (this applies for alpha, beta and release candidates).

2: Release sub-modules

For each sub-module, from the release branch:

  1. Remove any ibc-go replace directives in the sub-module's go.mod.
replace (
-   github.com/cosmos/ibc-go/v10 => ../../../
  1. Update the ibc-go version in the sub-modules's go.mod to the version release in the previous step.
-  github.com/cosmos/ibc-go/v10 v10.3.0
+  github.com/cosmos/ibc-go/v10 v10.4.0
  1. Create a PR to the release branch, and after CI finishes, merge it.
  2. Create a new release in GitHub with "Draft new release".
  3. Select the release branch (e.g. release/v10.4.x)
  4. Set the correct tag (e.g. modules/light-clients/08-wasm/v10.4.0)
  5. Write release notes
  6. Check the This is a pre-release checkbox if needed (this applies for alpha, beta and release candidates).

3: Post-release procedure

  1. Clean up the release branch
  • Put back the sub-module replace directives in the sub-module's go.mod.
  • Put back the [Unreleased] section in the release branch (e.g. release/v1.0.x) with clean sections for each of the types of changelog entries, so that entries will be added for the PRs that are backported for the next release.
  1. Clean up the main branch
  • Update CHANGELOG.md in main (remove from the [Unreleased] section any items that are part of the release).`
  • Update version matrix in RELEASES.md: add the new release and remove any tags that might not be recommended anymore.
  • Additionally, for the first point release of a new major or minor release branch:
    • Update the table of supported release lines (and End of Life dates) in RELEASES.md: add the new release line and remove any release lines that might have become discontinued.
    • Update the list of supported release lines in README.md, if necessary.
    • Update the manual e2e simd test workflow:
      • Remove any tags that might not be recommended anymore.
    • Update docs site:
      • If the release is occurring on the main branch, on the latest version, then run npm run docusaurus docs:version vX.Y.Z in the docs/ directory. (where X.Y.Z is the new version number)
      • If the release is occurring on an older release branch, then make a PR to the main branch called docs: new release vX.Y.Z doing the following:
        • Update the content of the docs found in docs/versioned_docs/version-vx.y.z if needed. (where x.y.z is the previous version number)
        • Update the version number of the older release branch by changing the version number of the older release branch in:
          • In docs/versions.json.
          • Rename docs/versioned_sidebars/version-vx.y.z-sidebars.json
          • Rename docs/versioned_docs/version-vx.y.z
    • After changes to docs site are deployed, check ibc.cosmos.network is updated.

Point release procedure

In order to alleviate the burden for a single person to have to cherry-pick and handle merge conflicts of all desired backporting PRs to a point release, we instead maintain a living backport branch, where all desired features and bug fixes are merged into as separate PRs.

Example

Current release is v1.0.2. We then maintain a (living) branch release/v1.0.x, given x as the next patch release number (currently v1.0.3) for the v1.0 release series. As bugs are fixed and PRs are merged into main, if a contributor wishes the PR to be released into the v1.0.x point release, the contributor must:

  1. Add the backport-to-v1.0.x label to the PR.
  2. Once the PR is merged, the Mergify GitHub application will automatically copy the changes into another branch and open a new PR against the desired release/v1.0.x branch.
  3. If the following has not been discussed in the original PR, then update the backport PR's description and ensure it contains the following information:
  • [Impact] explanation of how the bug affects users or developers.
  • [Test Case] section with detailed instructions on how to reproduce the bug.
  • [Regression Potential] section with a discussion how regressions are most likely to manifest, or might manifest even if it's unlikely, as a result of the change. It is assumed that any backport PR is well-tested before it is merged in and has an overall low risk of regression. This section should discuss the potential for state breaking changes to occur such as through out-of-gas errors.

It is the PR's author's responsibility to fix merge conflicts, update changelog entries, and ensure CI passes. If a PR originates from an external contributor, it may be a core team member's responsibility to perform this process instead of the original author. Lastly, it is core team's responsibility to ensure that the PR meets all the backport criteria.

Finally, when a point release is ready to be made:

  1. Checkout the release branch (e.g. release/v1.0.x).
  2. In CHANGELOG.md:
  • Ensure changelog entries are verified.
  • Remove any sections of the changelog that do not have any entries (e.g. if the release does not have any bug fixes, then remove the section).
  • Remove the [Unreleased] title.
  • Add release version and date of release.
  1. Create release in GitHub:
  • Select the correct target branch (e.g. release/v1.0.x).
  • Choose a tag (e.g. v1.0.3).
  • Write release notes.
  • Check the This is a pre-release checkbox if needed (this applies for alpha, beta and release candidates).