58597139fa
## Description Closes: #9404 --- ### 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... - [x] 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 - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [x] 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 - [x] reviewed "Files changed" and left comments if necessary - [x] 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)
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# Specification of Specifications
|
|
|
|
This file intends to outline the common structure for specifications within
|
|
this directory.
|
|
|
|
## Tense
|
|
|
|
For consistency, specs should be written in passive present tense.
|
|
|
|
## Pseudo-Code
|
|
|
|
Generally, pseudo-code should be minimized throughout the spec. Often, simple
|
|
bulleted-lists which describe a function's operations are sufficient and should
|
|
be considered preferable. In certain instances, due to the complex nature of
|
|
the functionality being described pseudo-code may the most suitable form of
|
|
specification. In these cases use of pseudo-code is permissible, but should be
|
|
presented in a concise manner, ideally restricted to only the complex
|
|
element as a part of a larger description.
|
|
|
|
## Common Layout
|
|
|
|
The following generalized file structure should be used to breakdown
|
|
specifications for modules. With the exception of README.md, `XX` at the
|
|
beginning of the file name should be replaced with a number to indicate
|
|
document flow (ex. read `01_state.md` before `02_state_transitions.md`). The
|
|
following list is nonbinding and all files are optional.
|
|
|
|
* `README.md` - overview of the module
|
|
* `XX_concepts.md` - describe specialized concepts and definitions used throughout the spec
|
|
* `XX_state.md` - specify and describe structures expected to marshalled into the store, and their keys
|
|
* `XX_state_transitions.md` - standard state transition operations triggered by hooks, messages, etc.
|
|
* `XX_messages.md` - specify message structure(s) and expected state machine behaviour(s)
|
|
* `XX_begin_block.md` - specify any begin-block operations
|
|
* `XX_end_block.md` - specify any end-block operations
|
|
* `XX_hooks.md` - describe available hooks to be called by/from this module
|
|
* `XX_events.md` - list and describe event tags used
|
|
* `XX_client.md` - list and describe CLI commands and gRPC and REST endpoints
|
|
* `XX_params.md` - list all module parameters, their types (in JSON) and examples
|
|
* `XX_future_improvements.md` - describe future improvements of this module
|
|
* `XX_tests.md` - acceptance tests
|
|
* `XX_appendix.md` - supplementary details referenced elsewhere within the spec
|
|
|
|
### Notation for key-value mapping
|
|
|
|
Within `state.md` the following notation `->` should be used to describe key to
|
|
value mapping:
|
|
|
|
```text
|
|
key -> value
|
|
```
|
|
|
|
to represent byte concatenation the `|` may be used. In addition, encoding
|
|
type may be specified, for example:
|
|
|
|
```text
|
|
0x00 | addressBytes | address2Bytes -> amino(value_object)
|
|
```
|
|
|
|
Additionally, index mappings may be specified by mapping to the `nil` value, for example:
|
|
|
|
```text
|
|
0x01 | address2Bytes | addressBytes -> nil
|
|
```
|