docs: store spec template/guideline #14020
Conversation
store/SPEC_STANDARD.md
Outdated
| } | ||
| ``` | ||
|
|
||
| Pseudocode for algorithms should be written in simple Typescript, as functions. |
There was a problem hiding this comment.
I think it is going to be quite hard to translate
|
Thanks all for the comments! |
store/SPEC_STANDARD.md
Outdated
|
|
||
| ### System model and properties | ||
|
|
||
| This section should include an assumptions sub-section if any, and the mandatory properties sub-section. Note that both sub-sections are tightly coupled: how to enforce a property will depend directly on the assumptions made. |
There was a problem hiding this comment.
I think the important thing to capture here is the "rest of the world", that is,
- Which modules are used by the module under specification, and what do we expect from them
- If possible, which module use the module under specification and how.
For instance, let's assume module A uses module B. There might be the implicit assumption that module B panics in certain situations, and this is fine, as we want A to panic in this situations as well. This is an assumption we need to make explicit in the specification.
With this information, we obtain:
a. We understand what A is doing as a result of the behavior of B
b. If we ever go to redesign B, we need to understand that other modules (e.g. A) rely on maintaining this specific behavior (e.g., we still need to panic in this situation).
I guess Point 1. would go into the assumption paragraph and Point 2 in the property paragraph.
|
I have done a pass to generalize it and include @josef-widder comment. The only pending comment is whether to use agnostic-language pseudocode or simply go. Also, we should decide where to place this document (does not make sense to have it within the store folder). |
store/SPEC_STANDARD.md
Outdated
| @@ -0,0 +1,116 @@ | |||
| ## What is a SDK standard? | |||
|
|
|||
| A SDK standard is a design document describing a particular protocol, standard, or feature expected to be used by the Cosmos SDK. A SDK standard should list the desired properties of the standard, explain the design rationale, and provide a concise but comprehensive technical specification. The primary author is responsible for pushing the proposal through the standardization process, soliciting input and support from the community, and communicating with relevant stakeholders to ensure (social) consensus. | |||
There was a problem hiding this comment.
This seems to me to be too broad. Do you mean what is an SDK Storage or State standard?
There was a problem hiding this comment.
What do you mean by State standard?
This seems to me to be too broad.
This is intended. The first version was specific for store features, but reviewers requested to generalize it. I thought there was consensus, but we can discuss it and figure out what's best.
There was a problem hiding this comment.
Then why is it under the store package?
There was a problem hiding this comment.
We have to move it. Since the original was for store-related features, I put it here. After generalizing it, I am not sure where to put it so I haven't moved it. See #14020 (comment)
There was a problem hiding this comment.
If it's not a specification standard template specifically for storage/state, then it doesn't belong in store/. The docs/spec directory would be a perfectly adequate place to put it :)
The document should be under docs/spec (https://github.com/cosmos/cosmos-sdk/tree/main/docs/spec). This way it will be rendered on docs.cosmos.network as well. |
Co-authored-by: Aleksandr Bezobchuk <[email protected]>
Co-authored-by: Aleksandr Bezobchuk <[email protected]>
| - history log, and | ||
| - copyright notice. | ||
|
|
||
| All top-level sections are required. References should be included inline as links, or tabulated at the bottom of the section if necessary. Included sub-sections should be listed in the order specified below. |
There was a problem hiding this comment.
A table a content is as well handy.
Description
Contributes to: #12986
Proposes a spec template/guideline for store-related specification documents. There is overlapping between the format section of the document and the documentation writing guidelines. We could simply remove the former.
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...
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...
!in the type prefix if API or client breaking change