chore: package release prep + update UPGRADING.md (#22864)

(cherry picked from commit 8ff9f48) # Conflicts: # README.md # RELEASE_PROCESS.md # UPGRADING.md # collections/CHANGELOG.md # core/testing/CHANGELOG.md # docs/docs/build/building-modules/00-intro.md # schema/CHANGELOG.md # store/CHANGELOG.md # x/group/go.mod # x/group/testutil/app_config.go
cosmos · Dec 16, 2024 · d1c54b3 · d1c54b3
1 parent 3b082b5
commit d1c54b3
Show file tree

Hide file tree

Showing 10 changed files with 1,001 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -34,9 +34,13 @@
 
 The Cosmos SDK is a framework for building blockchain applications. [CometBFT (BFT Consensus)](https://github.com/cometbft/cometbft) and the Cosmos SDK are written in the Go programming language. Cosmos SDK is used to build [Gaia](https://github.com/cosmos/gaia), the implementation of the Cosmos Hub.
 
+<<<<<<< HEAD
 **WARNING**: The Cosmos SDK has mostly stabilized, but we are still making some breaking changes.
 
 **Note**: We advise to always use the latest maintained [Go](https://go.dev/dl) version for building Cosmos SDK applications.
+=======
+**Note**: Always use the latest maintained [Go](https://go.dev/dl) version for building Cosmos SDK applications.
+>>>>>>> 8ff9f48bb (chore: package release prep + update UPGRADING.md (#22864))
 
 ## Quick Start
 
@@ -64,6 +68,58 @@ The Cosmos Hub application, `gaia`, has its own [cosmos/gaia repository](https:/
 
 The IBC module for the Cosmos SDK has its own [cosmos/ibc-go repository](https://github.com/cosmos/ibc-go). Go there to build and integrate with the IBC module.
 
+<<<<<<< HEAD
+=======
+### Version Matrix
+
+The version matrix below shows which versions of the Cosmos SDK, modules and libraries are compatible with each other.
+
+> [!IMPORTANT]
+> Cosmos SDK `v2` corresponds to a chain using the `runtime/v2`, `server/v2/**`, and `store/v2` packages. The `github.com/cosmos/cosmos-sdk` module has a less important role in a `v2` chain.
+
+#### Core Dependencies
+
+Core dependencies are the core libraries that an application may depend on.
+Core dependencies not mentioned here as compatible across all maintained SDK versions.
+See an exhaustive list of core dependencies at [cosmossdk.io](https://cosmossdk.io).
+
+| Version                  | v2    | 0.52.z    | 0.50.z         | 0.47.z  |
+| ------------------------ | ----- | --------- | -------------- | ------- |
+| cosmossdk.io/core        | 1.y.z | 1.y.z     | 0.11.z         | 0.5.z   |
+| cosmossdk.io/api         | 0.8.z | 0.8.z     | 0.7.z          | 0.3.z   |
+| cosmossdk.io/x/tx        | 1.y.z | 1.y.z     | < 1.y.z        | N/A     |
+| cosmossdk.io/store       | N/A   | >= 1.10.z | 1.0.0 >= 1.9.z | N/A     |
+| cosmossdk.io/store/v2    | 2.y.z | N/A       | N/A            | N/A     |
+| cosmossdk.io/collections | 1.y.z | 1.y.z     | < 1.y.z        | < 1.y.z |
+
+#### Module Dependencies
+
+Module Dependencies are the modules that an application may depend on and which version of the Cosmos SDK they are compatible with.
+
+> Note: The version table only goes back to 0.50.x, as modules started to become modular with 0.50.z.
+> X signals that the module was not spun out into its own go.mod file.
+> N/A signals that the module was not available in the Cosmos SDK at that time.
+
+| Cosmos SDK                  | v2    | 0.52.z | 0.50.z |
+| --------------------------- | ----- | ------ | ------ |
+| cosmossdk.io/x/accounts     | 0.2.z | 0.2.z  | N/A    |
+| cosmossdk.io/x/bank         | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/circuit      | 0.2.z | 0.2.z  | 0.1.z  |
+| cosmossdk.io/x/consensus    | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/distribution | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/epochs       | 0.2.z | 0.2.z  | N/A    |
+| cosmossdk.io/x/evidence     | 0.2.z | 0.2.z  | 0.1.z  |
+| cosmossdk.io/x/feegrant     | 0.2.z | 0.2.z  | 0.1.z  |
+| cosmossdk.io/x/gov          | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/group        | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/mint         | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/nft          | 0.2.z | 0.2.z  | 0.1.z  |
+| cosmossdk.io/x/protocolpool | 0.2.z | 0.2.z  | N/A    |
+| cosmossdk.io/x/slashing     | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/staking      | 0.2.z | 0.2.z  | X      |
+| cosmossdk.io/x/upgrade      | 0.2.z | 0.2.z  | 0.1.z  |
+
+>>>>>>> 8ff9f48bb (chore: package release prep + update UPGRADING.md (#22864))
 ## Disambiguation
 
 This Cosmos SDK project is not related to the [React-Cosmos](https://github.com/react-cosmos/react-cosmos) project (yet). Many thanks to Evan Coury and Ovidiu (@skidding) for this Github organization name. As per our agreement, this disambiguation notice will stay here.
diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md
@@ -237,6 +237,10 @@ Those modules can be considered as part of the Cosmos SDK, but features and impr
 * 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.
 * 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.
 
+> [!IMPORTANT]  
+> A module depending on a non stabilized version of `github.com/cosmos/cosmos-sdk` (any version prior to the removal of baseapp, runtime, server) SHOULD NOT be tagged following semver.
+> For instance, modules are still using 0ver until the main `github.com/cosmos/cosmos-sdk` has stabilized.
+
 ### Modules that do not depend on the Cosmos SDK
 
 Modules that do not depend on the Cosmos SDK can be released at any time from the `main` branch of the Cosmos SDK repository.
@@ -245,4 +249,29 @@ Modules that do not depend on the Cosmos SDK can be released at any time from th
 
 Branches that go modules are released from:
 
+<<<<<<< HEAD
 * Store v1 is released from `release/v0.50.x` branch.
+=======
+Here's the strategy for managing this structure:
+
+All modules that do not depend on the Cosmos SDK and tagged from main in a release branch **must be removed from the release branch**.
+
+There are two exceptions to this rule, due to the stabilization of core v1: `cosmossdk.io/x/tx` and `cosmossdk.io/store` are still tagged from the `release/v0.50.x` branch for `v0.50.x` releases.
+
+### Rationale
+
+This strategy provides several benefits:
+
+1. Clean separation: Release branches only contain components that are actually released from those branches.
+2. Avoid confusion: Prevents having outdated versions of standalone go modules in release branches.
+3. Accurate representation: The release branch accurately represents what's being released from that branch.
+4. Consistency: Aligns with the tagging strategy - components tagged from main aren't in release branches, and vice versa.
+
+### Additional Considerations
+
+* When backporting changes, be aware that standalone go modules changes will not be present in release branches.
+* To reference the full state of the SDK at the time of branching, consider creating a separate tag on main at the point where each release branch is created.
+* Ensure thorough testing of the release branch structure to avoid any integration issues.
+
+This branching strategy helps maintain a clear separation between components tagged from main and those tagged from release branches, while ensuring that release branches accurately represent the state of components that depend on the SDK.
+>>>>>>> 8ff9f48bb (chore: package release prep + update UPGRADING.md (#22864))