docs(adr): Update protobuf guidelines with Since (#10672)

<!--
The default pull request template is for types feat, fix, or refactor.
For other templates, add one of the following parameters to the url:
- template=docs.md
- template=other.md
-->

## Description

I've been telling people to add this `Since:` comment in some PRs, but noticed it's not documented anywhere. I updated the relevant PR from the conclusions of TX working group calls with @aaronc, @webmaster128 and myself.

<!-- Add a description of the changes that this PR introduces and the files that
are the most critical to review. -->

---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
This commit is contained in:
Amaury 2021-12-07 12:17:34 +01:00 committed by GitHub
parent 1d436638af
commit 47cc86df7b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -3,6 +3,7 @@
## Changelog
- 28.06.2021: Initial Draft
- 02.12.2021: Add `Since:` comment for new fields
## Status
@ -47,10 +48,38 @@ For this reason, module developers MUST NOT add new fields to existing `Msg`s.
It is worth mentioning that this does not limit adding fields to a `Msg`, but also to all nested structs and `Any`s inside a `Msg`.
#### 2. Non-`Msg`-related Protobuf definitions MAY have new fields
#### 2. Non-`Msg`-related Protobuf definitions MAY have new fields, but MUST add a `Since:` comment
On the other hand, module developers MAY add new fields to Protobuf definitions related to the `Query` service or to objects which are saved in the store. This recommendation follows the Protobuf specification, but is added in this document for clarity.
The SDK requires the Protobuf comment of the new field to contain one line with the following format:
```protobuf
// Since: cosmos-sdk <version>{, <version>...}
```
Where each `version` denotes a minor ("0.45") or patch ("0.44.5") version from which the field is available. This will greatly help client libraries, who can optionally use reflection or custom code generation to show/hide these fields depending on the targetted node version.
As examples, the following comments are valid:
```protobuf
// Since: cosmos-sdk 0.44
// Since: cosmos-sdk 0.42.11, 0.44.5
```
and the following ones are NOT valid:
```protobuf
// Since cosmos-sdk v0.44
// since: cosmos-sdk 0.44
// Since: cosmos-sdk 0.42.11 0.44.5
// Since: Cosmos SDK 0.42.11, 0.44.5
```
#### 3. Fields MAY be marked as `deprecated`, and nodes MAY implement a protocol-breaking change for handling these fields
Protobuf supports the [`deprecated` field option](https://developers.google.com/protocol-buffers/docs/proto#options), and this option MAY be used on any field, including `Msg` fields. If a node handles a Protobuf message with a non-empty deprecated field, the node MAY change its behavior upon processing it, even in a protocol-breaking way. When possible, the node MUST handle backwards compatibility without breaking the consensus (unless we increment the proto version).
@ -70,7 +99,7 @@ TODO, needs architecture review. Some topics:
- Bumping versions frequency
- When bumping versions, should the Cosmos SDK support both versions?
- i.e. v1beta1 -> v1, should we have two folders in the Cosmos SDK, and handlers for both versions?
- i.e. v1beta1 -> v1, should we have two folders in the Cosmos SDK, and handlers for both versions?
- mention ADR-023 Protobuf naming
## Consequences