diff --git a/RELEASES.md b/RELEASES.md new file mode 100644 index 00000000000..90ba9675d42 --- /dev/null +++ b/RELEASES.md @@ -0,0 +1,44 @@ +# Releases + +IBC-Go follows [semantic versioning](https://semver.org), but with the following deviations: + +- A state-machine breaking change will result in an increase of the minor version Y (x.Y.z | x > 0). +- An API breaking change will result in an increase of the major number (X.y.z | x > 0). Please note that these changes **will be backwards compatible** (as opposed to canonical semantic versioning; read [Backwards compatibility](#backwards) for a detailed explanation). + +This is visually explained in the following decision tree: + +![](releases-decision-tree.png) + +When bumping the dependencies of [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) and [Tendermint](https://github.com/tendermint/tendermint) we will only treat patch releases as non state-machine breaking. + +## Backwards compatibility + +[ibc-go](https://github.com/cosmos/ibc-go) and the [IBC protocol specification](https://github.com/cosmos/ibc) maintain different versions. Furthermore, ibc-go serves several different user groups (chains, IBC app developers, relayers, IBC light client developers). Each of these groups has different expectations of what *backwards compatible* means. It simply isn't possible to categorize a change as backwards or non backwards compatible for all user groups. We are primarily interested in when our API breaks and when changes are state machine breaking (thus requiring a coordinated upgrade). This is scoping the meaning of ibc-go to that of those interacting with the code (IBC app developers, relayers, IBC light client developers), not chains using IBC to communicate (that should be encapsulated by the IBC protocol specification versioning). + +To summarize: **All our ibc-go releases allow chains to communicate successfully with any chain running any version of our code**. That is to say, we are still using IBC protocol specification v1.0. + +We ensure all major releases are supported by relayers ([hermes](https://github.com/informalsystems/ibc-rs) and [ts-relayer](https://github.com/confio/ts-relayer) at the moment) which can relay between the new major release and older releases. We have no plans of upgrading to an IBC protocol specification v2.0, as this would be very disruptive to the ecosystem. + +## Graphics + +The decision tree above was generated with the following code: + +``` +%%{init: + {'theme': 'default', + 'themeVariables': + {'fontFamily': 'verdana', 'fontSize': '13px'} + } +}%% +flowchart TD + A(Change):::c --> B{state-machine breaking?} + B:::c --> |Yes| C{API breaking?} + B:::c --> |No| D{API breaking?} + C:::c --> |Yes| E(Increase major version):::c + C:::c --> |No| F(Increase minor version):::c + D:::c --> |Yes| G(Increase major version):::c + D:::c --> |No| H(Increase patch version):::c + classDef c fill:#eee,stroke:#aaa +``` + +using [Mermaid's live editor](https://mermaid-js.github.io/). \ No newline at end of file diff --git a/releases-decision-tree.png b/releases-decision-tree.png new file mode 100644 index 00000000000..3b03462c6b0 Binary files /dev/null and b/releases-decision-tree.png differ