-
Notifications
You must be signed in to change notification settings - Fork 134
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: adding some info on ICS processes (#1429)
* moving docs/old/testing.md to TESTING.md * adding release process * adding info on ICS releases * updating contributing guidelines * apply review suggestions * Update RELEASES.md Co-authored-by: insumity <[email protected]> * Update RELEASES.md Co-authored-by: insumity <[email protected]> * adding note about editor for unclog * add some context on breaking changes * adding context on state-compatibility * Update STATE-COMPATIBILITY.md Co-authored-by: insumity <[email protected]> --------- Co-authored-by: insumity <[email protected]>
- Loading branch information
Showing
6 changed files
with
487 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| # Releases | ||
|
|
||
| - [Releases](#releases) | ||
| - [Semantic Versioning](#semantic-versioning) | ||
| - [Breaking Changes](#breaking-changes) | ||
| - [Release Cycle](#release-cycle) | ||
| - [Stable Release Policy](#stable-release-policy) | ||
| - [Version Matrix](#version-matrix) | ||
| - [Backwards Compatibility](#backwards-compatibility) | ||
|
|
||
| ## Semantic Versioning | ||
|
|
||
| Interchain Security (ICS) follows [semantic versioning](https://semver.org), but with the following deviations (similar to [IBC-Go](https://github.com/cosmos/ibc-go/blob/main/RELEASES.md)): | ||
|
|
||
| - A library API breaking change will result in an increase of the MAJOR version number (X.y.z | X > 0). | ||
| - A state-machine breaking change will result in an increase of the MINOR version number (x.Y.z | x > 0). | ||
| - Any other changes (including node API breaking changes) will result in an increase of the PATCH version number (x.y.Z | x > 0). | ||
|
|
||
| ### Breaking Changes | ||
|
|
||
| A change is considered to be ***library API breaking*** if it modifies the integration of ICS on either consumer or provider chains (i.e., it changes the way ICS is used as a library). | ||
| Note that bumping the major version of [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) or [IBC](https://github.com/cosmos/ibc-go) will be considered as a library API breaking change. | ||
|
|
||
| A change is considered to be ***state-machine breaking*** if it requires a coordinated upgrade and/or state migration for either consumer or provider chains in order to preserve [state compatibility](./STATE-COMPATIBILITY.md). | ||
| Note that when bumping the dependencies of [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) and [IBC](https://github.com/cosmos/ibc-go) we will only treat patch releases as non state-machine breaking. | ||
|
|
||
| A change is considered to be ***node API breaking*** if it modifies the API provided by a node of either consumer or provider chains. | ||
| This includes events, queries, CLI interfaces. | ||
|
|
||
| ## Release Cycle | ||
|
|
||
| ICS follows a traditional release cycle involving release candidates (RCs) releases before finalizing a new version. | ||
| The stable release guarantees do not go into affect until a final release is performed. | ||
|
|
||
| ❗***It is never advisable to use a non-final release in production.*** | ||
|
|
||
| Final releases should contain little to no changes in comparison to the latest RC. | ||
|
|
||
| A release should not be finalized until the development team and the external community have done sufficient integration tests on the targeted release. | ||
|
|
||
| ## Stable Release Policy | ||
|
|
||
| The beginning of a new major release series is marked by the release of a new major version. | ||
| A major release series is comprised of all minor and patch releases made under the same major version number. | ||
| The series continues to receive bug fixes (released as minor or patch releases) until it reaches end of life. | ||
| The date when a major release series reaches end of life is determined by one of the following methods: | ||
|
|
||
| - If there is no known chain using a major release series, then it reached end of life. | ||
| This is a temporary policy that is possible due to the relatively low number of consumer chains. | ||
| - If the next major release is made within the first 6 months, then the end of | ||
| life date of the major release series is 1 year after its initial release. | ||
| - If the next major release is made 6 months after the initial release, then the | ||
| end of life date of the major release series is 6 months after the release date | ||
| of the next major release. | ||
|
|
||
| Only the following major release series have a stable release status. | ||
| All missing minor release versions have been discontinued. | ||
|
|
||
| | Release | End of Life Date | | ||
| |---------|------------------| | ||
| | `v1.2.x` | February 21, 2024 | | ||
| | `v2.0.x` | June 09, 2024 | | ||
| | `v2.1.x-provider-lsm` | June 09, 2024 | | ||
| | `v2.3.x-provider-lsm` | June 09, 2024 | | ||
| | `v3.1.x` | July 10, 2024 | | ||
| | `v3.2.x` | July 10, 2024 | | ||
|
|
||
| **Note**: As of [Gaia v12.0.0](https://github.com/cosmos/gaia/releases/tag/v12.0.0), | ||
| the Cosmos Hub uses a fork of Cosmos SDK ([v0.45.16-ics-lsm](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.45.16-ics-lsm)) | ||
| that contains the Liquid Staking Module (LSM). | ||
| This means the Cosmos Hub requires a fork of ICS. | ||
| This fork is maintained by the development team and released using the `-lsm` prefix. | ||
| As soon as the Cosmos Hub uses mainline Cosmos SDK, the `-lsm` releases will reach end of life. | ||
|
|
||
| ## Version Matrix | ||
|
|
||
| Versions of Golang, IBC, Cosmos SDK and CometBFT used by ICS in the currently active releases: | ||
|
|
||
| | ICS | Golang | IBC | Cosmos SDK | CometBFT | Note | | ||
| |-----|--------|-----|------------|----------|------| | ||
| | [v1.2.0-multiden](https://github.com/cosmos/interchain-security/releases/tag/v1.2.0-multiden) | 1.18 | v4.2.0 | v0.45.15-ics | v0.34.27 | Consumer only | | ||
| | [v2.0.0](https://github.com/cosmos/interchain-security/releases/tag/v2.0.0) | 1.19 | v4.4.2 | v0.45.15-ics | v0.34.28 | | ||
| | [v2.1.0-provider-lsm](https://github.com/cosmos/interchain-security/releases/tag/v2.1.0-provider-lsm) | 1.19 | v4.4.2 | v0.45.16-ics-lsm | v0.34.28 | Provider only (Cosmos Hub specific) | | ||
| | [v2.3.0-provider-lsm](https://github.com/cosmos/interchain-security/releases/tag/v2.3.0-provider-lsm) | 1.19 | v4.4.2 | v0.45.16-ics-lsm | v0.34.28 | Provider only (Cosmos Hub specific) | | ||
| | [v3.1.0](https://github.com/cosmos/interchain-security/releases/tag/v3.1.0) | 1.20 | v7.1.0 | v0.47.3 | v0.37.2 | | ||
|
|
||
| ### Backwards Compatibility | ||
|
|
||
| A MAJOR version of ICS will always be backwards compatible with the previous MAJOR version of ICS. | ||
|
|
||
| The following table indicates the compatibility of currently active releases: | ||
|
|
||
| | consumer | provider | `v2.0.0` | `v2.1.0-provider-lsm` | `v2.3.0-provider-lsm` | `v3.1.0` | | ||
| |----------|----------|--------:|----------------------:|----------------------:|---------:| | ||
| | `v1.2.0-multiden` || ✅ | ✅ | ✅ | ✅ | | ||
| | `v2.0.0` || ✅ | ✅ | ✅ | ✅ | | ||
| | `v3.1.0` || ✅ | ✅ | ✅ | ✅ | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,119 @@ | ||
| # Release Process | ||
|
|
||
| - [Release Process](#release-process) | ||
| - [Changelog](#changelog) | ||
| - [Creating a new release branch](#creating-a-new-release-branch) | ||
| - [Cutting a new release](#cutting-a-new-release) | ||
| - [Update the changelog on main](#update-the-changelog-on-main) | ||
| - [Tagging Procedure](#tagging-procedure) | ||
|
|
||
|
|
||
| This document outlines the release process for Interchain Security (ICS). | ||
|
|
||
| For details on ICS releases, see [RELEASES.md](./RELEASES.md). | ||
|
|
||
| ## Changelog | ||
|
|
||
| For PRs that are changing production code, please add a changelog entry in `.changelog` (for details, see [contributing guidelines](./CONTRIBUTING.md#changelog)). | ||
|
|
||
| To manage and generate the changelog on ICS, we currently use [unclog](https://github.com/informalsystems/unclog). | ||
| Read the [README.md](https://github.com/informalsystems/unclog#readme) in the unclog repo for instruction on how to install and use unclog. | ||
|
|
||
| ### Creating a new release branch | ||
|
|
||
| Unreleased changes are collected on `main` in `.changelog/unreleased/`. | ||
| However, `.changelog/` on `main` contains also existing releases (e.g., `v3.2.0`). | ||
| Thus, when creating a new release branch (e.g., `release/v3.3.x`), the following steps are necessary: | ||
|
|
||
| - create a new release branch, e.g., `release/v3.3.x` | ||
| ```bash | ||
| git checkout main | ||
| git pull | ||
| git checkout -b release/v3.3.x | ||
| ``` | ||
| - delete all the sub-folders in `.changelog/` except `unreleased/` | ||
| ```bash | ||
| find ./.changelog -mindepth 1 -maxdepth 1 -type d -not -name unreleased | xargs rm -r | ||
| ``` | ||
| - replace the content of `.changelog/epilogue.md` with the following text | ||
| ```md | ||
| ## Previous Versions | ||
| [CHANGELOG of previous versions](https://github.com/cosmos/interchain-security/blob/main/CHANGELOG.md) | ||
| ``` | ||
| - push the release branch upstream | ||
| ```bash | ||
| git push | ||
| ``` | ||
|
|
||
| ### Cutting a new release | ||
|
|
||
| Before cutting a _**release candidate**_ (e.g., `v3.3.0-rc0`), the following steps are necessary: | ||
|
|
||
| - move to the release branch, e.g., `release/v3.3.x` | ||
| ```bash | ||
| git checkout release/v3.3.x | ||
| ``` | ||
| - move all entries in ".changelog/unreleased" to the release version, e.g., `v3.3.0`, i.e., | ||
| ```bash | ||
| unclog release v3.3.0 | ||
| ``` | ||
| - update `CHANGELOG.md`, i.e., | ||
| ```bash | ||
| unclog build > CHANGELOG.md | ||
| ``` | ||
| - open a PR (from this new created branch) against the release branch, e.g., `release/v3.3.x` | ||
|
|
||
| Now you can cut the release candidate, e.g., v3.3.0-rc0 (follow the [Tagging Procedure](#tagging-procedure)). | ||
|
|
||
| ### Update the changelog on main | ||
|
|
||
| Once the **final release** is cut, the new changelog section must be added to main: | ||
|
|
||
| - checkout a new branch from the `main` branch, i.e., | ||
| ```bash | ||
| git checkout main | ||
| git pull | ||
| git checkout -b <username>/backport_changelog | ||
| ``` | ||
| - bring the new changelog section from the release branch into this branch, e.g., | ||
| ```bash | ||
| git checkout release/v3.3.x .changelog/v3.3.0 | ||
| ``` | ||
| - remove duplicate entries that are both in `.changelog/unreleased/` and the new changelog section, e.g., `.changelog/v3.3.0` | ||
| - update `CHANGELOG.md`, i.e., | ||
| ```bash | ||
| unclog build > CHANGELOG.md | ||
| ``` | ||
| - open a PR (from this new created branch) against `main` | ||
|
|
||
| ## Tagging Procedure | ||
|
|
||
| **Important**: _**Always create tags from your local machine**_ since all release | ||
| tags should be [signed and annotated](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). | ||
|
|
||
| The following steps are the default for tagging a specific branch commit using git | ||
| on your local machine. Usually, release branches are labeled `release/v*`: | ||
|
|
||
| Ensure you have checked out the commit you wish to tag and then do: | ||
| ```bash | ||
| git pull --tags | ||
| git tag -s v3.2.0 -m v3.2.0 | ||
| git push origin v3.2.0 | ||
| ``` | ||
|
|
||
| To re-create a tag: | ||
| ```bash | ||
| # delete a tag locally | ||
| git tag -d v3.2.0 | ||
| # push the deletion to the remote | ||
| git push --delete origin v3.2.0 | ||
| # redo the tagging | ||
| git tag -s v3.2.0 -m v3.2.0 | ||
| git push origin v3.2.0 | ||
| ``` | ||
|
|
||
| For final releases, once the tag is created, use the GitHub interface to create a release. | ||
| Note that this is not necessary for release candidates. |
Oops, something went wrong.