docs: store spec template/guideline #14020

angbrav · 2022-11-25T11:58:52Z

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

included the correct docs: prefix in the PR title
targeted the correct branch (see PR Targeting)
provided a link to the relevant issue or specification
followed the documentation writing guidelines
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 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)

store/SPEC_STANDARD.md

tac0turtle

left 2 questions but overall looks good to me

odeke-em

Thank you @angbrav for this work, I've added some suggestions, please take a look.Thank you Marko and Julien for the co-reviews!

store/SPEC_STANDARD.md

odeke-em · 2022-11-26T23:36:30Z

store/SPEC_STANDARD.md

+}
+```
+
+Pseudocode for algorithms should be written in simple Typescript, as functions.


I think it is going to be quite hard to translate

store/SPEC_STANDARD.md

angbrav · 2022-11-28T11:43:56Z

Thanks all for the comments!

josef-widder · 2022-11-28T12:50:47Z

store/SPEC_STANDARD.md

+
+### 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.


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.

angbrav · 2022-11-29T11:28:06Z

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

alexanderbez · 2022-11-29T16:55:24Z

store/SPEC_STANDARD.md

@@ -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.


This seems to me to be too broad. Do you mean what is an SDK Storage or State standard?

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.

Then why is it under the store package?

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)

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

julienrbrt · 2022-11-30T20:22:18Z

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

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 <alexanderbez@users.noreply.github.com>

addressed comments

julienrbrt

lgtm

julienrbrt · 2022-12-05T16:48:08Z

docs/spec/SPEC_STANDARD.md

+- 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. 


A table a content is as well handy.

docs/spec/SPEC_STANDARD.md

angbrav added 2 commits November 24, 2022 16:11

first draft store-spec-standard

e161303

minor changes

301045d

angbrav requested a review from a team as a code owner November 25, 2022 11:58

github-actions bot added the C:Store label Nov 25, 2022

tac0turtle reviewed Nov 25, 2022

View reviewed changes

store/SPEC_STANDARD.md Outdated Show resolved Hide resolved

tac0turtle reviewed Nov 25, 2022

View reviewed changes

store/SPEC_STANDARD.md Outdated Show resolved Hide resolved

julienrbrt reviewed Nov 25, 2022

View reviewed changes

store/SPEC_STANDARD.md Outdated Show resolved Hide resolved

tac0turtle reviewed Nov 25, 2022

View reviewed changes

odeke-em previously requested changes Nov 26, 2022

View reviewed changes

josef-widder reviewed Nov 28, 2022

View reviewed changes

tac0turtle assigned aaronc, alexanderbez, tac0turtle and julienrbrt Nov 28, 2022

generalize

b84edd4

alexanderbez reviewed Nov 29, 2022

View reviewed changes

tac0turtle and others added 4 commits December 5, 2022 14:00

Merge branch 'main' into manuel/store-spec-standard

bf5d4f5

Update store/SPEC_STANDARD.md

24dee46

Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com>

Update store/SPEC_STANDARD.md

e603194

Co-authored-by: Aleksandr Bezobchuk <alexanderbez@users.noreply.github.com>

move and write golang

4fe864e

github-actions bot removed the C:Store label Dec 5, 2022

tac0turtle requested review from julienrbrt and alexanderbez December 5, 2022 14:11

julienrbrt approved these changes Dec 5, 2022

View reviewed changes

tac0turtle reviewed Dec 5, 2022

View reviewed changes

docs/spec/SPEC_STANDARD.md Show resolved Hide resolved

Update docs/spec/SPEC_STANDARD.md

0978f5d

Merge branch 'main' into manuel/store-spec-standard

83e6e9d

tac0turtle enabled auto-merge (squash) December 5, 2022 22:38

tac0turtle merged commit a31c4ac into main Dec 5, 2022

tac0turtle deleted the manuel/store-spec-standard branch December 5, 2022 22:39

angbrav mentioned this pull request Jan 6, 2023

docs: inter-block cache specification #14370

Merged

14 tasks

julienrbrt mentioned this pull request Jan 16, 2023

docs: update specs to use go code #14629

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: store spec template/guideline #14020

docs: store spec template/guideline #14020

angbrav commented Nov 25, 2022 •

edited

Loading

tac0turtle left a comment

odeke-em left a comment

odeke-em Nov 26, 2022

angbrav commented Nov 28, 2022

josef-widder Nov 28, 2022

angbrav commented Nov 29, 2022

alexanderbez Nov 29, 2022

angbrav Nov 29, 2022 •

edited

Loading

alexanderbez Nov 29, 2022

angbrav Nov 29, 2022

alexanderbez Dec 1, 2022

julienrbrt commented Nov 30, 2022 •

edited

Loading

julienrbrt left a comment

julienrbrt Dec 5, 2022


		### 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.

		@@ -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.

docs: store spec template/guideline #14020

docs: store spec template/guideline #14020

Conversation

angbrav commented Nov 25, 2022 • edited Loading

Description

Author Checklist

Reviewers Checklist

tac0turtle left a comment

Choose a reason for hiding this comment

odeke-em left a comment

Choose a reason for hiding this comment

odeke-em Nov 26, 2022

Choose a reason for hiding this comment

angbrav commented Nov 28, 2022

josef-widder Nov 28, 2022

Choose a reason for hiding this comment

angbrav commented Nov 29, 2022

alexanderbez Nov 29, 2022

Choose a reason for hiding this comment

angbrav Nov 29, 2022 • edited Loading

Choose a reason for hiding this comment

alexanderbez Nov 29, 2022

Choose a reason for hiding this comment

angbrav Nov 29, 2022

Choose a reason for hiding this comment

alexanderbez Dec 1, 2022

Choose a reason for hiding this comment

julienrbrt commented Nov 30, 2022 • edited Loading

julienrbrt left a comment

Choose a reason for hiding this comment

julienrbrt Dec 5, 2022

Choose a reason for hiding this comment

angbrav commented Nov 25, 2022 •

edited

Loading

angbrav Nov 29, 2022 •

edited

Loading

julienrbrt commented Nov 30, 2022 •

edited

Loading