Skip to content

Commit

Permalink
docs: Improve markdownlint configuration (cosmos#11104)
Browse files Browse the repository at this point in the history
## Description

Closes: cosmos#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)
  • Loading branch information
julienrbrt authored Feb 10, 2022
1 parent b1f9a11 commit 5859713
Show file tree
Hide file tree
Showing 212 changed files with 3,793 additions and 3,756 deletions.
14 changes: 4 additions & 10 deletions .markdownlint.json
Original file line number Diff line number Diff line change
@@ -1,17 +1,11 @@
{
"default": true,
"MD001": false,
"MD004": false,
"MD004": {"style": "asterisk"},
"MD007": { "indent": 4 },
"MD013": false,
"MD024": { "siblings_only": true },
"MD025": false,
"MD026": { "punctuation": ".,;:" },
"MD029": false,
"MD033": false,
"MD034": false,
"MD036": false,
"MD040": false,
"MD041": false,
"no-hard-tabs": false
}
"no-hard-tabs": false,
"whitespace": false
}
2 changes: 1 addition & 1 deletion .markdownlintignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
CHANGELOG.md
docs/node_modules
/README.md
2,138 changes: 1,074 additions & 1,064 deletions CHANGELOG.md

Large diffs are not rendered by default.

108 changes: 54 additions & 54 deletions CODING_GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,32 @@ This document is an extension to [CONTRIBUTING](./CONTRIBUTING.md) and provides

## API & Design

+ Code must be well structured:
+ packages must have a limited responsibility (different concerns can go to different packages),
+ types must be easy to compose,
+ think about maintainbility and testability.
+ "Depend upon abstractions, [not] concretions".
+ Try to limit the number of methods you are exposing. It's easier to expose something later than to hide it.
+ Take advantage of `internal` package concept.
+ Follow agreed-upon design patterns and naming conventions.
+ publicly-exposed functions are named logically, have forward-thinking arguments and return types.
+ Avoid global variables and global configurators.
+ Favor composable and extensible designs.
+ Minimize code duplication.
+ Limit third-party dependencies.
* Code must be well structured:
* packages must have a limited responsibility (different concerns can go to different packages),
* types must be easy to compose,
* think about maintainbility and testability.
* "Depend upon abstractions, [not] concretions".
* Try to limit the number of methods you are exposing. It's easier to expose something later than to hide it.
* Take advantage of `internal` package concept.
* Follow agreed-upon design patterns and naming conventions.
* publicly-exposed functions are named logically, have forward-thinking arguments and return types.
* Avoid global variables and global configurators.
* Favor composable and extensible designs.
* Minimize code duplication.
* Limit third-party dependencies.

Performance:

+ Avoid unnecessary operations or memory allocations.
* Avoid unnecessary operations or memory allocations.

Security:

+ Pay proper attention to exploits involving:
+ gas usage
+ transaction verification and signatures
+ malleability
+ code must be always deterministic
+ Thread safety. If some functionality is not thread-safe, or uses something that is not thread-safe, then clearly indicate the risk on each level.
* Pay proper attention to exploits involving:
* gas usage
* transaction verification and signatures
* malleability
* code must be always deterministic
* Thread safety. If some functionality is not thread-safe, or uses something that is not thread-safe, then clearly indicate the risk on each level.

## Acceptance tests

Expand All @@ -43,24 +43,24 @@ UAT should be revisited at each stage of the product development:

![acceptance-tests.png](./docs/assets/acceptance-tests.png)

### Why Acceptance Testing?
### Why Acceptance Testing

- Automated acceptance tests catch serious problems that unit or component test suites could never catch.
- Automated acceptance tests deliver business value the users are expecting as they test user scenarios.
- Automated acceptance tests executed and passed on every build help improve the software delivery process.
- Testers, developers, and customers need to work closely to create suitable automated acceptance test suites.
* Automated acceptance tests catch serious problems that unit or component test suites could never catch.
* Automated acceptance tests deliver business value the users are expecting as they test user scenarios.
* Automated acceptance tests executed and passed on every build help improve the software delivery process.
* Testers, developers, and customers need to work closely to create suitable automated acceptance test suites.

### How to define Acceptance Test?
### How to define Acceptance Test

The best way to define AT is by starting from the user stories and think about all positive and negative scenarios a user can perform.

Product Developers should collaborate with stakeholders to define AT. Functional experts and business users are both needed for defining AT.

A good pattern for defining AT is listing scenarios with [GIVEN-WHEN-THEN](https://martinfowler.com/bliki/GivenWhenThen.html) format where:

- **GIVEN**: A set of initial circumstances (e.g. bank balance)
- **WHEN**: Some event happens (e.g. customer attempts a transfer)
- **THEN**: The expected result as per the defined behavior of the system
* **GIVEN**: A set of initial circumstances (e.g. bank balance)
* **WHEN**: Some event happens (e.g. customer attempts a transfer)
* **THEN**: The expected result as per the defined behavior of the system

In other words: we define a use case input, current state and the expected outcome. Example:

Expand All @@ -79,9 +79,9 @@ In other words: we define a use case input, current state and the expected outco
*Reference: [writing acceptance tests](https://openclassrooms.com/en/courses/4544611-write-agile-documentation-user-stories-acceptance-tests/4810081-writing-acceptance-tests)*.

### How and where to add acceptance tests?
### How and where to add acceptance tests

Acceptance tests are written in the Markdown format, using the scenario template described above, and be part of the specification (`xx_test.md` file in _spec_ directory). Example: (`eco-credits/spec/06.test.md`)[https://github.com/regen-network/regen-ledger/blob/7297783577e6cd102c5093365b573163680f36a1/x/ecocredit/spec/06_tests.md]
Acceptance tests are written in the Markdown format, using the scenario template described above, and be part of the specification (`xx_test.md` file in *spec* directory). Example: [`eco-credits/spec/06.test.md`](https://github.com/regen-network/regen-ledger/blob/7297783577e6cd102c5093365b573163680f36a1/x/ecocredit/spec/06_tests.md).

Acceptance tests should be defined during the design phase or at an early stage of development. Moreover, they should be defined before writing a module architecture - it will clarify the purpose and usage of the software.
Automated tests should cover all acceptance tests scenarios.
Expand All @@ -90,11 +90,11 @@ Automated tests should cover all acceptance tests scenarios.

Make sure your code is well tested:

+ Provide unit tests for every unit of your code if possible. Unit tests are expected to comprise 70%-80% of your tests.
+ Describe the test scenarios you are implementing for integration tests.
+ Create integration tests for queries and msgs.
+ Use both test cases and property / fuzzy testing. We use the [rapid](pgregory.net/rapid) Go library for property-based and fuzzy testing.
+ Do not decrease code test coverage. Explain in a PR if test coverage is decreased.
* Provide unit tests for every unit of your code if possible. Unit tests are expected to comprise 70%-80% of your tests.
* Describe the test scenarios you are implementing for integration tests.
* Create integration tests for queries and msgs.
* Use both test cases and property / fuzzy testing. We use the [rapid](pgregory.net/rapid) Go library for property-based and fuzzy testing.
* Do not decrease code test coverage. Explain in a PR if test coverage is decreased.

We expect tests to use `require` or `assert` rather than `t.Skip` or `t.Fail`,
unless there is a reason to do otherwise.
Expand Down Expand Up @@ -122,31 +122,31 @@ for tcIndex, tc := range cases {
We are forming a QA team that will support the core Cosmos SDK team and collaborators by:
- Improving the Cosmos SDK QA Processes
- Improving automation in QA and testing
- Defining high-quality metrics
- Maintaining and improving testing frameworks (unit tests, integration tests, and functional tests)
- Defining test scenarios.
- Verifying user experience and defining a high quality.
- We want to have **acceptance tests**! Document and list acceptance lists that are implemented and identify acceptance tests that are still missing.
- Acceptance tests should be specified in `acceptance-tests` directory as Markdown files.
- Supporting other teams with testing frameworks, automation, and User Experience testing.
- Testing chain upgrades for every new breaking change.
- Defining automated tests that assure data integrity after an update.
* Improving the Cosmos SDK QA Processes
* Improving automation in QA and testing
* Defining high-quality metrics
* Maintaining and improving testing frameworks (unit tests, integration tests, and functional tests)
* Defining test scenarios.
* Verifying user experience and defining a high quality.
* We want to have **acceptance tests**! Document and list acceptance lists that are implemented and identify acceptance tests that are still missing.
* Acceptance tests should be specified in `acceptance-tests` directory as Markdown files.
* Supporting other teams with testing frameworks, automation, and User Experience testing.
* Testing chain upgrades for every new breaking change.
* Defining automated tests that assure data integrity after an update.
Desired outcomes:
- QA team works with Development Team.
- QA is happening in parallel with Core Cosmos SDK development.
- Releases are more predictable.
- QA reports. Goal is to guide with new tasks and be one of the QA measures.
* QA team works with Development Team.
* QA is happening in parallel with Core Cosmos SDK development.
* Releases are more predictable.
* QA reports. Goal is to guide with new tasks and be one of the QA measures.
As a developer, you must help the QA team by providing instructions for User Experience (UX) and functional testing.
### QA Team to cross check Acceptance Tests
Once the AT are defined, the QA team will have an overview of the behavior a user can expect and:
- validate the user experience will be good
- validate the implementation conforms the acceptance tests
- by having a broader overview of the use cases, QA team should be able to define **test suites** and test data to efficiently automate Acceptance Tests and reuse the work.
* validate the user experience will be good
* validate the implementation conforms the acceptance tests
* by having a broader overview of the use cases, QA team should be able to define **test suites** and test data to efficiently automate Acceptance Tests and reuse the work.
Loading

0 comments on commit 5859713

Please sign in to comment.