Skip to content

Commit

Permalink
docs: minor fixes to spec template (#14369)
Browse files Browse the repository at this point in the history
  • Loading branch information
angbrav authored Dec 20, 2022
1 parent edb5c1c commit 3aa16ed
Showing 1 changed file with 20 additions and 19 deletions.
39 changes: 20 additions & 19 deletions docs/spec/SPEC_STANDARD.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
## What is an SDK standard?
# What is an SDK standard?

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

## Sections

A SDK standard consists of:
- a synopsis,
- overview and basic concepts,
- technical specification,
- history log, and
- copyright notice.

* a synopsis,
* overview and basic concepts,
* technical specification,
* 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.

### Table Of Contents
### Table Of Contents

> Provide a table of contents at the top of the file to assist readers.
Provide a table of contents at the top of the file to assist readers.

### Synopsis

Expand All @@ -25,27 +26,27 @@ The document should include a brief (~200 word) synopsis providing a high-level

This section should include a motivation sub-section and a definitions sub-section if required:

- *Motivation* - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature.
- *Definitions* - A list of new terms or concepts utilized in the document or required to understand it.
* *Motivation* - A rationale for the existence of the proposed feature, or the proposed changes to an existing feature.
* *Definitions* - A list of new terms or concepts utilized in the document or required to understand it.

### System model and properties

This section should include an assumptions sub-section if any, the mandatory properties sub-section, and a dependencies sub-section. Note that the first two sub-section are are tightly coupled: how to enforce a property will depend directly on the assumptions made. This sub-section is important to capture the interactions of the specified feature with the "rest-of-the-world", i.e., with other features of the ecosystem.

- *Assumptions* - A list of any assumptions made by the feature designer. It should capture which features are used by the feature under specification, and what do we expect from them.
- *Properties* - A list of the desired properties or characteristics of the feature specified, and expected effects or failures when the properties are violated. In case it is relevant, it can also include a list of properties that the feature does not guarantee.
- *Dependencies* - A list of the features that use the feature under specification and how.
* *Assumptions* - A list of any assumptions made by the feature designer. It should capture which features are used by the feature under specification, and what do we expect from them.
* *Properties* - A list of the desired properties or characteristics of the feature specified, and expected effects or failures when the properties are violated. In case it is relevant, it can also include a list of properties that the feature does not guarantee.
* *Dependencies* - A list of the features that use the feature under specification and how.

### Technical specification

This is the main section of the document, and should contain protocol documentation, design rationale, required references, and technical details where appropriate.
The section may have any or all of the following sub-sections, as appropriate to the particular specification. The API sub-section is especially encouraged when appropriate.

- *API* - A detailed description of the features's API.
- *Technical Specification* - All technical details including syntax, diagrams, semantics, protocols, data structures, algorithms, and pseudocode as appropriate. The technical specification should be detailed enough such that separate correct implementations of the specification without knowledge of each other are compatible.
- *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions.
- *Known Issues* - A list of known issues. This sub-section is specially important for specifications of already in-use features.
- *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers.
* *API* - A detailed description of the features's API.
* *Technical Details* - All technical details including syntax, diagrams, semantics, protocols, data structures, algorithms, and pseudocode as appropriate. The technical specification should be detailed enough such that separate correct implementations of the specification without knowledge of each other are compatible.
* *Backwards Compatibility* - A discussion of compatibility (or lack thereof) with previous feature or protocol versions.
* *Known Issues* - A list of known issues. This sub-section is specially important for specifications of already in-use features.
* *Example Implementation* - A concrete example implementation or description of an expected implementation to serve as the primary reference for implementers.

### History

Expand Down Expand Up @@ -76,7 +77,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
Pseudocode in specifications should be language-agnostic and formatted in a simple imperative standard, with line numbers, variables, simple conditional blocks, for loops, and
English fragments where necessary to explain further functionality such as scheduling timeouts. LaTeX images should be avoided because they are difficult to review in diff form.

Pseudocode for structs can be written in a simple langauge like Typescript or golang, as interfaces.
Pseudocode for structs can be written in a simple language like Typescript or golang, as interfaces.

Example Typescript pseudocode struct:

Expand Down

0 comments on commit 3aa16ed

Please sign in to comment.