diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8975d37269..1c702cb100 100644 --- a/CONTRIBUTING.md +++ b/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.