docs: adding some info on ICS processes

CONTRIBUTING.md

@@ -14,11 +14,10 @@
     - [Pull Request Templates](#pull-request-templates)
     - [Requesting Reviews](#requesting-reviews)
     - [Updating Documentation](#updating-documentation)
+    - [Changelog](#changelog)
   - [Dependencies](#dependencies)
   - [Protobuf](#protobuf)
   - [Branching Model and Release](#branching-model-and-release)
-    - [Semantic Versioning](#semantic-versioning)
-    - [Backwards Compatibility](#backwards-compatibility)
     - [PR Targeting](#pr-targeting)
 
 Thank you for considering making contributions to the Interchain Security (ICS) repository! 🎉👍
@@ -216,6 +215,58 @@ items. In addition, use the following review explanations:
 
 If you open a PR in ICS, it is mandatory to update the relevant documentation in `/docs`.
 
+### Changelog
+
+To manage and generate our changelog, we currently use [unclog](https://github.com/informalsystems/unclog).
+
+Every PR with types `fix`, `feat`, `deps`, and `refactor` should include a file 
+`.changelog/unreleased/${section}/[${component}/]${pr-number}-${short-description}.md`,
+where:
+
+- `section` is one of 
+  `dependencies`, `improvements`, `features`, `bug-fixes`, `state-breaking`, `api-breaking`, 
+  and _**if multiple apply, create multiple files**_;
+- `pr-number` is the PR number;
+- `short-description` is a short (4 to 6 word), hyphen separated description of the change;
+- `component` is used for changes that affect one of the components defined in the [config](.changelog/config.toml), e.g., `provider`, `consumer`.
+
+For examples, see the [.changelog](.changelog) folder.
+
+Use `unclog` to add a changelog entry in `.changelog` (check the [requirements](https://github.com/informalsystems/unclog#requirements) first): 
+```bash
+# add a general entry
+unclog add 
+   -i "${pr-number}-${short-description}" 
+   -p "${pr-number}" 
+   -s "${section}" 
+   -m "${description}"
+
+# add a entry to a component 
+unclog add 
+   -i "${pr-number}-${short-description}" 
+   -p "${pr-number}" 
+   -c "${component}"
+   -s "${section}" 
+   -m "${description}"
+```
+where `${description}` is a detailed description of the changelog entry.
+
+For example, 
+```bash
+# add an entry for bumping IBC to v7.2.0
+unclog add -i "1196-bump-ibc" -p 1196 -s dependencies -m "Bump [ibc-go](https://github.com/cosmos/ibc-go) to [v7.2.0](https://github.com/cosmos/ibc-go/releases/tag/v7.2.0)" 
+
+# add an entry for changing the consumer module;
+# note that the entry is added to both state-breaking and features sections
+unclog add -i "1024-jail-throttling-v2" -p 1024 -c consumer -s state-breaking -m "Add the consumer-side changes for jail throttling with retries (cf. ADR 008)." 
+unclog add -i "1024-jail-throttling-v2" -p 1024 -c consumer -s features -m "Add the consumer-side changes for jail throttling with retries (cf. ADR 008)." 
+```
+
+**Note:** Changelog entries should answer the question: "what is important about this
+change for users to know?" or "what problem does this solve for users?". It
+should not simply be a reiteration of the title of the associated PR, unless the
+title of the PR _very_ clearly explains the benefit of a change to a user.
+
 ## Dependencies
 
 We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage
@@ -243,18 +294,6 @@ To generate the protobuf stubs, you can run `make proto-gen`.
 
 ICS adheres to the [trunk based development branching model](https://trunkbaseddevelopment.com/). User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`.
 
-### Semantic Versioning
-
-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 breaking change (change requiring coordinated upgrade and/or state migration for the consumer, the provider, or both) 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).
-
-### Backwards Compatibility
-
-A MAJOR version of ICS will always be backwards compatible with the previous MAJOR version of ICS. Versions before that are not supported. For example, a provider chain could run ICS at version 3.4.5, and would be compatible with consumers running ICS at 2.0.0, 2.1.2, 3.2.1, but not 1.2.7.
-
 ### PR Targeting
 
 Ensure that you base and target your PRs on either `main` or a feature branch.

README.md

@@ -43,7 +43,7 @@ Inspect the [Makefile](./Makefile) if curious.
 
 ## Testing
 
-See [testing docs](./docs/old/testing.md).
+See [testing docs](./TESTING.md).
 
 ## Learn more
 

RELEASES.md

@@ -0,0 +1,90 @@
+# Releases
+
+- [Releases](#releases)
+  - [Semantic Versioning](#semantic-versioning)
+  - [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 (change requiring coordinated upgrade and/or state migration for the consumer, the provider, or both) 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).
+
+❗**State compatibility**: It is critical for the patch releases to be state-machine compatible with prior releases in the same minor version. 
+For example, v3.2.1 must be state-machine compatible with v3.2.1.
+
+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.
+
+## 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` || ✅ | ✅ | ✅ | ✅ | 

RELEASE_PROCESS.md

@@ -0,0 +1,118 @@
+# 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.
+
+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.