Skip to content

Commit

Permalink
chore: Add "Since:" on proto doc comments (backport cosmos#10434) (co…
Browse files Browse the repository at this point in the history
…smos#10449)

* chore: Add "Since:" on proto doc comments (cosmos#10434)

<!--
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

ref: cosmos#10406 (reply in thread)

For clients to know whether a protobuf feature is available for a certain SDK version, we decided to use the [`@since` doc comment](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#@since) inside protobuf files.

<!-- 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)

(cherry picked from commit 0a3660d)

# Conflicts:
#	docs/core/proto-docs.md
#	proto/cosmos/bank/v1beta1/bank.proto
#	proto/cosmos/tx/v1beta1/tx.proto
#	types/tx/tx.pb.go
#	x/bank/types/bank.pb.go

* Fix conflicts

Co-authored-by: Amaury <[email protected]>
  • Loading branch information
2 people authored and JeancarloBarrios committed Sep 28, 2024
1 parent 379330c commit 697dd7c
Show file tree
Hide file tree
Showing 22 changed files with 110 additions and 31 deletions.
17 changes: 9 additions & 8 deletions client/grpc/cmtservice/query.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 7 additions & 3 deletions proto/cosmos/auth/v1beta1/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ option go_package = "github.com/cosmos/cosmos-sdk/x/auth/types";

// Query defines the gRPC querier service.
service Query {
// Accounts returns all the existing accounts.
// When called from another module, this query might consume a high amount of
// gas if the pagination field is incorrectly set.
// Accounts returns all the existing accounts
//
// Since: cosmos-sdk 0.43
rpc Accounts(QueryAccountsRequest) returns (QueryAccountsResponse) {
option (cosmos_proto.method_added_in) = "cosmos-sdk 0.43";
option (cosmos.query.v1.module_query_safe) = true;
Expand Down Expand Up @@ -81,13 +81,17 @@ service Query {
}

// QueryAccountsRequest is the request type for the Query/Accounts RPC method.
//
// Since: cosmos-sdk 0.43
message QueryAccountsRequest {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
// pagination defines an optional pagination for the request.
cosmos.base.query.v1beta1.PageRequest pagination = 1;
}

// QueryAccountsResponse is the response type for the Query/Accounts RPC method.
//
// Since: cosmos-sdk 0.43
message QueryAccountsResponse {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.47";
// accounts are the existing accounts
Expand Down
4 changes: 3 additions & 1 deletion proto/cosmos/base/query/v1beta1/pagination.proto
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@ message PageRequest {
bool count_total = 4;

// reverse is set to true if results are to be returned in the descending order.
bool reverse = 5 [(cosmos_proto.field_added_in) = "cosmos-sdk 0.43"];
//
// Since: cosmos-sdk 0.43
bool reverse = 5;
}

// PageResponse is to be embedded in gRPC response messages where the
Expand Down
3 changes: 2 additions & 1 deletion proto/cosmos/base/tendermint/v1beta1/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,8 @@ message VersionInfo {
string build_tags = 5;
string go_version = 6;
repeated Module build_deps = 7;
string cosmos_sdk_version = 8 [(cosmos_proto.field_added_in) = "cosmos-sdk 0.43"];
// Since: cosmos-sdk 0.43
string cosmos_sdk_version = 8;
}

// Module is the type for VersionInfo
Expand Down
4 changes: 3 additions & 1 deletion proto/cosmos/tx/v1beta1/service.proto
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,9 @@ message SimulateRequest {
// Deprecated. Send raw tx bytes instead.
cosmos.tx.v1beta1.Tx tx = 1 [deprecated = true];
// tx_bytes is the raw transaction.
bytes tx_bytes = 2 [(cosmos_proto.field_added_in) = "cosmos-sdk 0.43"];
//
// Since: cosmos-sdk 0.43
bytes tx_bytes = 2;
}

// SimulateResponse is the response type for the
Expand Down
8 changes: 5 additions & 3 deletions store/types/listening.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions types/query/pagination.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions types/tx/service.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

32 changes: 26 additions & 6 deletions x/auth/types/query.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions x/auth/vesting/proto/cosmos/vesting/v1beta1/vesting.proto
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ message PeriodicVestingAccount {
// PermanentLockedAccount implements the VestingAccount interface. It does
// not ever release coins, locking them indefinitely. Coins in this account can
// still be used for delegating and for governance votes even while locked.
//
// Since: cosmos-sdk 0.43
message PermanentLockedAccount {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
option (amino.name) = "cosmos-sdk/PermanentLockedAccount";
Expand Down
2 changes: 2 additions & 0 deletions x/bank/types/authz.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions x/bank/types/bank.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions x/bank/types/query.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 4 additions & 5 deletions x/gov/proto/cosmos/gov/v1beta1/gov.proto
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ enum VoteOption {
}

// WeightedVoteOption defines a unit of vote for vote split.
//
// Since: cosmos-sdk 0.43
message WeightedVoteOption {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
// option defines the valid vote options, it must not contain duplicate vote options.
Expand Down Expand Up @@ -190,12 +192,9 @@ message Vote {
// Deprecated: Prefer to use `options` instead. This field is set in queries
// if and only if `len(options) == 1` and that option has weight 1. In all
// other cases, this field will default to VOTE_OPTION_UNSPECIFIED.
VoteOption option = 3 [deprecated = true];

// options is the weighted vote options.
//
VoteOption option = 3 [deprecated = true];
// Since: cosmos-sdk 0.43
repeated WeightedVoteOption options = 4 [(gogoproto.nullable) = false, (amino.dont_omitempty) = true];
repeated WeightedVoteOption options = 4 [(gogoproto.nullable) = false];
}

// DepositParams defines the params for deposits on governance proposals.
Expand Down
4 changes: 2 additions & 2 deletions x/gov/types/v1beta1/gov.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 8 additions & 0 deletions x/gov/types/v1beta1/tx.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions x/staking/proto/cosmos/staking/v1beta1/authz.proto
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import "amino/amino.proto";
option go_package = "cosmossdk.io/x/staking/types";

// StakeAuthorization defines authorization for delegate/undelegate/redelegate.
//
// Since: cosmos-sdk 0.43
message StakeAuthorization {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
option (cosmos_proto.implements_interface) = "cosmos.authz.v1beta1.Authorization";
Expand Down
2 changes: 2 additions & 0 deletions x/staking/types/authz.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 8 additions & 1 deletion x/upgrade/proto/cosmos/upgrade/v1beta1/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ service Query {
}

// ModuleVersions queries the list of module versions from state.
//
// Since: cosmos-sdk 0.43
rpc ModuleVersions(QueryModuleVersionsRequest) returns (QueryModuleVersionsResponse) {
option (google.api.http).get = "/cosmos/upgrade/v1beta1/module_versions";
option (cosmos_proto.method_added_in) = "cosmos-sdk 0.43";
Expand Down Expand Up @@ -84,11 +86,14 @@ message QueryUpgradedConsensusStateResponse {
option deprecated = true;
reserved 1;

bytes upgraded_consensus_state = 2 [(cosmos_proto.field_added_in) = "cosmos-sdk 0.43"];
// Since: cosmos-sdk 0.43
bytes upgraded_consensus_state = 2;
}

// QueryModuleVersionsRequest is the request type for the Query/ModuleVersions
// RPC method.
//
// Since: cosmos-sdk 0.43
message QueryModuleVersionsRequest {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
// module_name is a field to query a specific module
Expand All @@ -99,6 +104,8 @@ message QueryModuleVersionsRequest {

// QueryModuleVersionsResponse is the response type for the Query/ModuleVersions
// RPC method.
//
// Since: cosmos-sdk 0.43
message QueryModuleVersionsResponse {
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
// module_versions is a list of module names with their consensus versions.
Expand Down
2 changes: 2 additions & 0 deletions x/upgrade/proto/cosmos/upgrade/v1beta1/upgrade.proto
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ message CancelSoftwareUpgradeProposal {
}

// ModuleVersion specifies a module and its consensus version.
//
// Since: cosmos-sdk 0.43
message ModuleVersion {
option (gogoproto.equal) = true;
option (cosmos_proto.message_added_in) = "cosmos-sdk 0.43";
Expand Down
Loading

0 comments on commit 697dd7c

Please sign in to comment.