docs: Improve markdownlint configuration (#11104 )

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

2022-02-10 12:07:01 +00:00

2.5 KiB

Raw Blame History

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:

key -> value

to represent byte concatenation the | may be used. In addition, encoding type may be specified, for example:

0x00 | addressBytes | address2Bytes -> amino(value_object)

Additionally, index mappings may be specified by mapping to the nil value, for example:

0x01 | address2Bytes | addressBytes -> nil

2.5 KiB Raw Blame History