github.com/cosmos/cosmos-sdk@v0.50.10/RELEASE_PROCESS.md (about)

     1  # Release Process
     2  
     3  This document outlines the process for releasing a new version of Cosmos SDK, which involves major release and patch releases as well as maintenance for the major release.
     4  
     5  > **Note, the Cosmos SDK went directly from v0.47 to v0.50 and skipped the v0.48 and v0.49 versions.**
     6  
     7  ## Major Release Procedure
     8  
     9  A _major release_ is an increment of the first number (eg: `v1.2` → `v2.0.0`) or the _point number_ (eg: `v1.1.0 → v1.2.0`, also called _point release_). Each major release opens a _stable release series_ and receives updates outlined in the [Major Release Maintenance](#major-release-maintenance)_section.
    10  
    11  Before making a new _major_ release we do beta and release candidate releases. For example, for release 1.0.0:
    12  
    13  ```text
    14  v1.0.0-beta1 → v1.0.0-beta2 → ... → v1.0.0-rc1 → v1.0.0-rc2 → ... → v1.0.0
    15  ```
    16  
    17  * Release a first beta version on the `main` branch and freeze `main` from receiving any new features. After beta is released, we focus on releasing the release candidate:
    18      * finish audits and reviews
    19      * kick off a large round of simulation testing (e.g. 400 seeds for 2k blocks)
    20      * perform functional tests
    21      * add more tests
    22      * release new beta version as the bugs are discovered and fixed.
    23  * After the team feels that the `main` works fine we create a `release/vY` branch (going forward known a release branch), where `Y` is the version number, with the patch part substituted to `x` (eg: 0.42.x, 1.0.x). Ensure the release branch is protected so that pushes against the release branch are permitted only by the release manager or release coordinator.
    24      * **PRs targeting this branch can be merged _only_ when exceptional circumstances arise**
    25      * update the GitHub mergify integration by adding instructions for automatically backporting commits from `main` to the `release/vY` using the `backport/Y` label.
    26  * In the release branch prepare a new version section in the `CHANGELOG.md`
    27      * All links must point to their respective pull request.
    28      * The `CHANGELOG.md` must contain only the changes of that specific released version. All other changelog entries must be deleted and linked to the `main` branch changelog ([example](https://github.com/cosmos/cosmos-sdk/blob/release/v0.46.x/CHANGELOG.md#previous-versions)).
    29      * Create release notes, in `RELEASE_NOTES.md`, highlighting the new features and changes in the version. This is needed so the bot knows which entries to add to the release page on GitHub.
    30      * Additionally verify that the `UPGRADING.md` file is up to date and contains all the necessary information for upgrading to the new version.
    31  * Remove GitHub workflows that should not be in the release branch
    32      * `deploy-docs.yml`: must be removed to avoid duplicate documentation deployment.
    33      * `test.yml`: All standalone go module tests should be removed (expect `./simapp`, and `./tests` and SDK tests).
    34          * These packages are tracked and tested directly on main.
    35      * `build.yml`: Only the SDK and SimApp needs to be built on release branches.
    36          * Tooling is tracked and tested directly on main.
    37  * Create a new annotated git tag for a release candidate (eg: `git tag -a v1.1.0-rc1`) in the release branch.
    38      * from this point we unfreeze main.
    39      * the SDK teams collaborate and do their best to run testnets in order to validate the release.
    40      * when bugs are found, create a PR for `main`, and backport fixes to the release branch.
    41      * create new release candidate tags after bugs are fixed.
    42  * After the team feels the release branch is stable and everything works, create a full release:
    43      * update `CHANGELOG.md`.
    44      * run `gofumpt -w -l .` to format the code.
    45      * create a new annotated git tag (eg `git -a v1.1.0`) in the release branch.
    46      * Create a GitHub release.
    47  
    48  Following _semver_ philosophy, point releases after `v1.0`:
    49  
    50  * must not break API
    51  * can break consensus
    52  
    53  Before `v1.0`, point release can break both point API and consensus.
    54  
    55  ## Patch Release Procedure
    56  
    57  A _patch release_ is an increment of the patch number (eg: `v1.2.0` → `v1.2.1`).
    58  
    59  **Patch release must not break API nor consensus.**
    60  
    61  Updates to the release branch should come from `main` by backporting PRs (usually done by automatic cherry pick followed by a PRs to the release branch). The backports must be marked using `backport/Y` label in PR for main.
    62  It is the PR author's responsibility to fix merge conflicts, update changelog entries, and
    63  ensure CI passes. If a PR originates from an external contributor, a core team member assumes
    64  responsibility to perform this process instead of the original author.
    65  Lastly, it is core team's responsibility to ensure that the PR meets all the SRU criteria.
    66  
    67  Point Release must follow the [Stable Release Policy](#stable-release-policy).
    68  
    69  After the release branch has all commits required for the next patch release:
    70  
    71  * Update `CHANGELOG.md` and `RELEASE_NOTES.md` (if applicable).
    72  * Create a new annotated git tag (eg `git -a v1.1.0`) in the release branch.
    73      * If the release is a submodule update, first go the submodule folder and name the tag prepending the path to the version:
    74        `cd core && git -a core/v1.1.0` or `cd tools/cosmovisor && git -a tools/cosmovisor/v1.4.0`
    75  * Create a GitHub release (if applicable).
    76  
    77  ## Major Release Maintenance
    78  
    79  Major Release series continue to receive bug fixes (released as a Patch Release) until they reach **End Of Life**.
    80  Major Release series is maintained in compliance with the **Stable Release Policy** as described in this document.
    81  
    82  Only the following major release series have a stable release status:
    83  
    84  * **0.46** is the previous major release and is supported until the release of **0.50.0**. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a not latest stable point-release.
    85  * **0.47** is the last major release and is supported until the release of **0.51.0**.
    86  
    87  The SDK team maintains the last two major releases, any other major release is considered to have reached end of life.
    88  The SDK team will not backport any bug fixes to releases that are not supported.
    89  Widely-used (decided at SDK team's discretion) unsupported releases are considered to be in a security maintenance mode. The SDK team will backport security fixes to these releases.
    90  
    91  ## Stable Release Policy
    92  
    93  ### Patch Releases
    94  
    95  Once a Cosmos-SDK release has been completed and published, updates for it are released under certain circumstances
    96  and must follow the [Patch Release Procedure](CONTRIBUTING.md#branching-model-and-release).
    97  
    98  ### Rationale
    99  
   100  Unlike in-development `main` branch snapshots, **Cosmos SDK** releases are subject to much wider adoption,
   101  and by a significantly different demographic of users. During development, changes in the `main` branch
   102  affect SDK users, application developers, early adopters, and other advanced users that elect to use
   103  unstable experimental software at their own risk.
   104  
   105  Conversely, users of a stable release expect a high degree of stability. They build their applications on it, and the
   106  problems they experience with it could be potentially highly disruptive to their projects.
   107  
   108  Stable release updates are recommended to the vast majority of developers, and so it is crucial to treat them
   109  with great caution. Hence, when updates are proposed, they must be accompanied by a strong rationale and present
   110  a low risk of regressions, i.e. even one-line changes could cause unexpected regressions due to side effects or
   111  poorly tested code. We never assume that any change, no matter how little or non-intrusive, is completely exempt
   112  of regression risks.
   113  
   114  Therefore, the requirements for stable changes are different than those that are candidates to be merged in
   115  the `main` branch. When preparing future major releases, our aim is to design the most elegant, user-friendly and
   116  maintainable SDK possible which often entails fundamental changes to the SDK's architecture design, rearranging and/or
   117  renaming packages as well as reducing code duplication so that we maintain common functions and data structures in one
   118  place rather than leaving them scattered all over the code base. However, once a release is published, the
   119  priority is to minimize the risk caused by changes that are not strictly required to fix qualifying bugs; this tends to
   120  be correlated with minimizing the size of such changes. As such, the same bug may need to be fixed in different
   121  ways in stable releases and `main` branch.
   122  
   123  ### Migrations
   124  
   125  See the SDK's policy on migrations [here](https://docs.cosmos.network/main/migrations/intro).
   126  
   127  ### What qualifies as a Stable Release Update (SRU)
   128  
   129  * **High-impact bugs**
   130      * Bugs that may directly cause a security vulnerability.
   131      * _Severe regressions_ from a Cosmos-SDK's previous release. This includes all sort of issues
   132      that may cause the core packages or the `x/` modules unusable.
   133      * Bugs that may cause **loss of user's data**.
   134  * Other safe cases:
   135      * Bugs which don't fit in the aforementioned categories for which an obvious safe patch is known.
   136      * Relatively small yet strictly non-breaking features with strong support from the community.
   137      * Relatively small yet strictly non-breaking changes that introduce forward-compatible client
   138      features to smoothen the migration to successive releases.
   139      * Relatively small yet strictly non-breaking CLI improvements.
   140  
   141  ### What does not qualify as SRU
   142  
   143  * State machine changes.
   144  * Breaking changes in Protobuf definitions, as specified in [ADR-044](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-044-protobuf-updates-guidelines.md).
   145  * Changes that introduces API breakages (e.g. public functions and interfaces removal/renaming).
   146  * Client-breaking changes in gRPC and HTTP request and response types.
   147  * CLI-breaking changes.
   148  * Cosmetic fixes, such as formatting or linter warning fixes.
   149  
   150  ### What pull requests will be included in stable point-releases
   151  
   152  Pull requests that fix bugs and add features that fall in the following categories do not require a **Stable Release Exception** to be granted to be included in a stable point-release:
   153  
   154  * **Severe regressions**.
   155  * Bugs that may cause **client applications** to be **largely unusable**.
   156  * Bugs that may cause **state corruption or data loss**.
   157  * Bugs that may directly or indirectly cause a **security vulnerability**.
   158  * Non-breaking features that are strongly requested by the community.
   159  * Non-breaking CLI improvements that are strongly requested by the community.
   160  
   161  ### What pull requests will NOT be automatically included in stable point-releases
   162  
   163  As rule of thumb, the following changes will **NOT** be automatically accepted into stable point-releases:
   164  
   165  * **State machine changes**.
   166  * **Protobug-breaking changes**, as specified in [ADR-044](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-044-protobuf-updates-       guidelines.md).
   167  * **Client-breaking changes**, i.e. changes that prevent gRPC, HTTP and RPC clients to continue interacting with the node without any change.
   168  * **API-breaking changes**, i.e. changes that prevent client applications to _build without modifications_ to the client application's source code.
   169  * **CLI-breaking changes**, i.e. changes that require usage changes for CLI users.
   170  
   171   In some circumstances, PRs that don't meet the aforementioned criteria might be raised and asked to be granted a _Stable Release Exception_.
   172  
   173  ### Stable Release Exception - Procedure
   174  
   175  1. Check that the bug is either fixed or not reproducible in `main`. It is, in general, not appropriate to release bug fixes for stable releases without first testing them in `main`. Please apply the label [v0.43](https://github.com/cosmos/cosmos-sdk/milestone/26) to the issue.
   176  2. Add a comment to the issue and ensure it contains the following information (see the bug template below):
   177  
   178     * **[Impact]** An explanation of the bug on users and justification for backporting the fix to the stable release.
   179     * A **[Test Case]** section containing detailed instructions on how to reproduce the bug.
   180     * A **[Regression Potential]** section with a clear assessment on how regressions are most likely to manifest as a result of the pull request that aims to fix the bug in the target stable release.
   181  
   182  3. **Stable Release Managers** will review and discuss the PR. Once _consensus_ surrounding the rationale has been reached and the technical review has successfully concluded, the pull request will be merged in the respective point-release target branch (e.g. `release/v0.43.x`) and the PR included in the point-release's respective milestone (e.g. `v0.43.5`).
   183  
   184  #### Stable Release Exception - Bug template
   185  
   186  ```md
   187  #### Impact
   188  
   189  Brief xplanation of the effects of the bug on users and a justification for backporting the fix to the stable release.
   190  
   191  #### Test Case
   192  
   193  Detailed instructions on how to reproduce the bug on Stargate's most recently published point-release.
   194  
   195  #### Regression Potential
   196  
   197  Explanation on how regressions might manifest - even if it's unlikely.
   198  It is assumed that stable release fixes are well-tested and they come with a low risk of regressions.
   199  It's crucial to make the effort of thinking about what could happen in case a regression emerges.
   200  ```
   201  
   202  ### Stable Release Managers
   203  
   204  The **Stable Release Managers** evaluate and approve or reject updates and backports to Cosmos SDK Stable Release series,
   205  according to the [stable release policy](#stable-release-policy) and [release procedure](#major-release-procedure).
   206  Decisions are made by consensus.
   207  
   208  Their responsibilites include:
   209  
   210  * Driving the Stable Release Exception process.
   211  * Approving/rejecting proposed changes to a stable release series.
   212  * Executing the release process of stable point-releases in compliance with the [Point Release Procedure](CONTRIBUTING.md).
   213  
   214  Currently residing Stable Release Managers:
   215  
   216  * @tac0turtle - Marko Baricevic
   217  * @julienrbrt - Julien Robert
   218  
   219  ## Cosmos SDK Modules
   220  
   221  The Cosmos SDK repository is a mono-repo where its Go modules have a different release process and cadence than the Cosmos SDK itself.
   222  There are two types of modules:
   223  
   224  1. Modules that import the Cosmos SDK and depend on a specific version of it.
   225      * Modules to be imported in an app (e.g `x/` modules).
   226      * Modules that are not imported into an app and are a standalone module (e.g. `cosmovisor`).
   227  2. Modules that do not depend on the Cosmos SDK.
   228  
   229  The same changelog procedure applies to all modules in the Cosmos SDK repository, and must be up-to-date with the latest changes before tagging a module version.
   230  Note: The Cosmos SDK team is in an active process of limiting Go modules that depend on the Cosmos SDK.
   231  
   232  ### Modules that depend on the Cosmos SDK
   233  
   234  The Cosmos SDK team should strive to release modules that depend on the Cosmos SDK at the same time or soon after a major version Cosmos SDK itself.
   235  Those modules can be considered as part of the Cosmos SDK, but features and improvements are released at a different cadence.
   236  
   237  * When a module is supposed to be used in an app (e.g `x/` modules), due to the dependency on the SDK, tagging a new version of a module must be done from a Cosmos SDK release branch. A compability matrix must be provided in the `README.md` of that module with the corresponding versions.
   238  * Modules that import the SDK but do not need to be imported in an app (`e.g. cosmovisor`) must be released from the `main` branch and follow the process defined below.
   239  
   240  ### Modules that do not depend on the Cosmos SDK
   241  
   242  Modules that do not depend on the Cosmos SDK can be released at any time from the `main` branch of the Cosmos SDK repository.
   243  
   244  #### Branches For Go Modules
   245  
   246  Branches that go modules are released from:
   247  
   248  * Store v1 is released from `release/v0.50.x` branch.