Skip to content

Commit

Permalink
chore: package release prep + update UPGRADING.md (#22864)
Browse files Browse the repository at this point in the history 
(cherry picked from commit 8ff9f48)

# Conflicts:
#	README.md
#	RELEASE_PROCESS.md
#	UPGRADING.md
#	collections/CHANGELOG.md
#	core/testing/CHANGELOG.md
#	schema/CHANGELOG.md
#	store/CHANGELOG.md
#	x/group/go.mod
  • Loading branch information
@julienrbrt @mergify
julienrbrt authored and mergify[bot] committed Dec 16, 2024
1 parent 356ca4e commit 00ab179
Show file tree
Hide file tree
Showing 10 changed files with 1,312 additions and 23 deletions.
53 changes: 33 additions & 20 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,6 @@

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.

**WARNING**: The Cosmos SDK has mostly stabilized, but we are still making some breaking changes.

**Note**: Always use the latest maintained [Go](https://go.dev/dl) version for building Cosmos SDK applications.

## Quick Start
Expand Down Expand Up @@ -64,16 +62,31 @@ The IBC module for the Cosmos SDK has its own [cosmos/ibc-go repository](https:/

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).

<<<<<<< HEAD
| Cosmos SDK | cosmossdk.io/core | cosmossdk.io/api | cosmossdk.io/x/tx |
| ---------- | ----------------- | ---------------- | ----------------- |
| 0.52.z | 1.y.z | 0.8.z | 0.14.z |
| 0.50.z | 0.11.z | 0.7.z | 0.13.z |
| 0.47.z | 0.5.z | 0.3.z | N/A |
=======
| 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 |
>>>>>>> 8ff9f48bb (chore: package release prep + update UPGRADING.md (#22864))
#### Module Dependencies

Expand All @@ -83,24 +96,24 @@ Module Dependencies are the modules that an application may depend on and which
> 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 | 0.50.z | 0.52.z |
| --------------------------- | ------ | ------ |
| cosmossdk.io/x/accounts | N/A | 0.2.z |
| cosmossdk.io/x/bank | X | 0.2.z |
| cosmossdk.io/x/circuit | 0.1.z | 0.2.z |
| cosmossdk.io/x/consensus | X | 0.2.z |
| cosmossdk.io/x/distribution | X | 0.2.z |
| cosmossdk.io/x/epochs | N/A | 0.2.z |
| cosmossdk.io/x/evidence | 0.1.z | 0.2.z |
| cosmossdk.io/x/feegrant | 0.1.z | 0.2.z |
| cosmossdk.io/x/gov | X | 0.2.z |
| cosmossdk.io/x/group | X | 0.2.z |
| cosmossdk.io/x/mint | X | 0.2.z |
| cosmossdk.io/x/nft | 0.1.z | 0.2.z |
| cosmossdk.io/x/protocolpool | N/A | 0.2.z |
| cosmossdk.io/x/slashing | X | 0.2.z |
| cosmossdk.io/x/staking | X | 0.2.z |
| cosmossdk.io/x/upgrade | 0.1.z | 0.2.z |
| 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 |

## Disambiguation

Expand Down
34 changes: 34 additions & 0 deletions RELEASE_PROCESS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,40 @@ 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 compatibility 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.
<<<<<<< HEAD
=======

## Go Monorepo Branching Strategy

The Cosmos SDK uses a monorepo structure with multiple Go modules. Some components are tagged from the main branch, while others are tagged from release branches, as described above.

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))
Loading

0 comments on commit 00ab179

Please sign in to comment.