|
14 | 14 | - [Pull Request Templates](#pull-request-templates) |
15 | 15 | - [Requesting Reviews](#requesting-reviews) |
16 | 16 | - [Updating Documentation](#updating-documentation) |
| 17 | + - [Changelog](#changelog) |
17 | 18 | - [Dependencies](#dependencies) |
18 | 19 | - [Protobuf](#protobuf) |
19 | 20 | - [Branching Model and Release](#branching-model-and-release) |
20 | | - - [Semantic Versioning](#semantic-versioning) |
21 | | - - [Backwards Compatibility](#backwards-compatibility) |
22 | 21 | - [PR Targeting](#pr-targeting) |
23 | 22 |
|
24 | 23 | Thank you for considering making contributions to the Interchain Security (ICS) repository! 🎉👍 |
@@ -216,6 +215,63 @@ items. In addition, use the following review explanations: |
216 | 215 |
|
217 | 216 | If you open a PR in ICS, it is mandatory to update the relevant documentation in `/docs`. |
218 | 217 |
|
| 218 | +### Changelog |
| 219 | + |
| 220 | +To manage and generate our changelog, we currently use [unclog](https://github.com/informalsystems/unclog). |
| 221 | + |
| 222 | +Every PR with types `fix`, `feat`, `deps`, and `refactor` should include a file |
| 223 | +`.changelog/unreleased/${section}/[${component}/]${pr-number}-${short-description}.md`, |
| 224 | +where: |
| 225 | + |
| 226 | +- `section` is one of |
| 227 | + `dependencies`, `improvements`, `features`, `bug-fixes`, `state-breaking`, `api-breaking`, |
| 228 | + and _**if multiple apply, create multiple files**_, |
| 229 | + not necessarily with the same `short-description` or content; |
| 230 | +- `pr-number` is the PR number; |
| 231 | +- `short-description` is a short (4 to 6 word), hyphen separated description of the change; |
| 232 | +- `component` is used for changes that affect one of the components defined in the [config](.changelog/config.toml), e.g., `provider`, `consumer`. |
| 233 | + |
| 234 | +For examples, see the [.changelog](.changelog) folder. |
| 235 | + |
| 236 | +Use `unclog` to add a changelog entry in `.changelog` (check the [requirements](https://github.com/informalsystems/unclog#requirements) first): |
| 237 | +```bash |
| 238 | +# add a general entry |
| 239 | +unclog add \ |
| 240 | + -i "${pr-number}-${short-description}" \ |
| 241 | + -p "${pr-number}" \ |
| 242 | + -s "${section}" \ |
| 243 | + -m "${description}" \ |
| 244 | + |
| 245 | +# add a entry to a component |
| 246 | +unclog add |
| 247 | + -i "${pr-number}-${short-description}" \ |
| 248 | + -p "${pr-number}" \ |
| 249 | + -c "${component}" \ |
| 250 | + -s "${section}" \ |
| 251 | + -m "${description}" \ |
| 252 | +``` |
| 253 | +where `${description}` is a detailed description of the changelog entry. |
| 254 | + |
| 255 | +For example, |
| 256 | +```bash |
| 257 | +# add an entry for bumping IBC to v7.2.0 |
| 258 | +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)" |
| 259 | + |
| 260 | +# add an entry for changing the consumer module; |
| 261 | +# note that the entry is added to both state-breaking and features sections |
| 262 | +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)." |
| 263 | +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)." |
| 264 | +``` |
| 265 | + |
| 266 | +**Note:** `unclog add` requires an editor. This can be set either by configuring |
| 267 | +an `$EDITOR` environment variable or by manually specify an editor binary path |
| 268 | +via the `--editor` flag. |
| 269 | + |
| 270 | +**Note:** Changelog entries should answer the question: "what is important about this |
| 271 | +change for users to know?" or "what problem does this solve for users?". It |
| 272 | +should not simply be a reiteration of the title of the associated PR, unless the |
| 273 | +title of the PR _very_ clearly explains the benefit of a change to a user. |
| 274 | + |
219 | 275 | ## Dependencies |
220 | 276 |
|
221 | 277 | We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage |
@@ -243,18 +299,6 @@ To generate the protobuf stubs, you can run `make proto-gen`. |
243 | 299 |
|
244 | 300 | 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`. |
245 | 301 |
|
246 | | -### Semantic Versioning |
247 | | - |
248 | | -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)): |
249 | | - |
250 | | -- A library API breaking change will result in an increase of the MAJOR version number (X.y.z | x > 0). |
251 | | -- 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). |
252 | | -- Any other changes (including node API breaking changes) will result in an increase of the PATCH version number (x.y.Z | x > 0). |
253 | | - |
254 | | -### Backwards Compatibility |
255 | | - |
256 | | -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. |
257 | | - |
258 | 302 | ### PR Targeting |
259 | 303 |
|
260 | 304 | Ensure that you base and target your PRs on either `main` or a feature branch. |
|
0 commit comments