Skip to content

docs: update release docs #8664

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
srdtrk merged 2 commits into from
Oct 10, 2025
Merged

docs: update release docs #8664

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
adce143
docs: update release docs
gjermundgaraba Oct 10, 2025
c7d2f15
cleaned up new brenach creation section
gjermundgaraba Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 69 additions & 30 deletions docs/dev/release-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Tagging a release

Before tagging a new release, please run the [compatibility e2e test suite](https://github.com/cosmos/ibc-go/actions/workflows/e2e-compatibility.yaml) for the corresponding release line.
## New release branch setup

## New major release branch
### New major release branch

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

Expand All @@ -14,16 +14,79 @@ 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
### 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 branch protection rules to new release branch.
2. Add backport task to [`mergify.yml`](https://github.com/cosmos/ibc-go/blob/main/.github/mergify.yml).
3. Create label for backport (e.g.`backport-to-v3.0.x`).
1. Add backport task to [`mergify.yml`](https://github.com/cosmos/ibc-go/blob/main/.github/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](#point-release-procedure).

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](https://github.com/cosmos/ibc-go/actions/workflows/e2e-compatibility.yaml) for the corresponding release line.
Copy link
Member

@srdtrk srdtrk Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we also run some upgrade tests?

Copy link
Contributor Author

@gjermundgaraba gjermundgaraba Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, good question. It was never part of the release flow. Maybe it should be. I don't have a super good overview over those tests, and if there would need to be any changes to support a specific branch or whatever 🤔

Copy link
Contributor Author

@gjermundgaraba gjermundgaraba Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I checked a bit more, and I don't know what the best procedure is, but what I did for v10.4.x leading up to the release was building a tag and updating ci-e2e-config.yaml:

  - planName: "v10"
    tag: "branch-release-v10.4.x"

Copy link
Contributor Author

@gjermundgaraba gjermundgaraba Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should I put this into the docs?

Copy link
Member

@srdtrk srdtrk Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. Maybe mark it optional if you don't always do this?

2. Make sure the CHANGELOG.md is updated.

### 1: Release ibc-go

1. Create a new release in [GitHub](https://github.com/cosmos/ibc-go/releases) 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`.
```diff
replace (
- github.com/cosmos/ibc-go/v10 => ../../../
```
2. Update the ibc-go version in the sub-modules's `go.mod` to the version release in the previous step.
```diff
- github.com/cosmos/ibc-go/v10 v10.3.0
+ github.com/cosmos/ibc-go/v10 v10.4.0
```
3. Create a PR to the release branch, and after CI finishes, merge it.
Copy link
Member

@srdtrk srdtrk Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do the e2e compatibility tests cover submodules?

Copy link
Contributor Author

@gjermundgaraba gjermundgaraba Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't look that way

Copy link
Contributor Author

@gjermundgaraba gjermundgaraba Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can see what it runs in e2e-compatibility.yaml

4. Create a new release in [GitHub](https://github.com/cosmos/ibc-go/releases) with "Draft new release".
5. Select the release branch (e.g. `release/v10.4.x`)
6. Set the correct tag (e.g. `modules/light-clients/08-wasm/v10.4.0`)
7. Write release notes
8. 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.
2. Clean up the main branch
- Update [`CHANGELOG.md`](../../CHANGELOG.md) in `main` (remove from the `[Unreleased]` section any items that are part of the release).`
- Update [version matrix](../../RELEASES.md#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`](../../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](../../RELEASES.md#releases), if necessary.
- Update the manual [e2e `simd`](https://github.com/cosmos/ibc-go/blob/main/.github/workflows/e2e-manual-simd.yaml) 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](https://ibc.cosmos.network) is updated.

## Point release procedure

Expand Down Expand Up @@ -60,27 +123,3 @@ Finally, when a point release is ready to be made:
- Write release notes.
- Check the `This is a pre-release` checkbox if needed (this applies for alpha, beta and release candidates).

### Post-release procedure

- Update [`CHANGELOG.md`](../../CHANGELOG.md) in `main` (remove from the `[Unreleased]` section any items that are part of the release).`
- 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.
- Update [version matrix](../../RELEASES.md#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`](../../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](../../RELEASES.md#releases), if necessary.
- Update the manual [e2e `simd`](https://github.com/cosmos/ibc-go/blob/main/.github/workflows/e2e-manual-simd.yaml) 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](https://ibc.cosmos.network) is updated.
- Open issue in [SDK tutorials repo](https://github.com/cosmos/sdk-tutorials) to update tutorials to the released version of ibc-go.

See [this PR](https://github.com/cosmos/ibc-go/pull/2919) for an example of the involved changes.
Loading