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)
This commit is contained in:
Julien Robert
+65
-60
@@ -1,20 +1,27 @@
|
||||
# Contributing
|
||||
|
||||
- [Contributing](#contributing)
|
||||
- [Dev Calls](#dev-calls)
|
||||
- [Architecture Decision Records (ADR)](#architecture-decision-records-adr)
|
||||
- [Development Procedure](#development-procedure)
|
||||
- [Testing](#testing)
|
||||
- [Pull Requests](#pull-requests)
|
||||
- [Pull Request Templates](#pull-request-templates)
|
||||
- [Requesting Reviews](#requesting-reviews)
|
||||
- [Updating Documentation](#updating-documentation)
|
||||
- [Dependencies](#dependencies)
|
||||
- [Protobuf](#protobuf)
|
||||
- [Branching Model and Release](#branching-model-and-release)
|
||||
- [PR Targeting](#pr-targeting)
|
||||
- [Code Owner Membership](#code-owner-membership)
|
||||
- [Concept & Feature Approval Process](#concept--feature-approval-process)
|
||||
* [Contributing](#contributing)
|
||||
* [Teams Dev Calls](#teams-dev-calls)
|
||||
* [Architecture Decision Records (ADR)](#architecture-decision-records-adr)
|
||||
* [Development Procedure](#development-procedure)
|
||||
* [Testing](#testing)
|
||||
* [Pull Requests](#pull-requests)
|
||||
* [Pull Request Templates](#pull-request-templates)
|
||||
* [Requesting Reviews](#requesting-reviews)
|
||||
* [Updating Documentation](#updating-documentation)
|
||||
* [Dependencies](#dependencies)
|
||||
* [Protobuf](#protobuf)
|
||||
* [Branching Model and Release](#branching-model-and-release)
|
||||
* [PR Targeting](#pr-targeting)
|
||||
* [Code Owner Membership](#code-owner-membership)
|
||||
* [Concept & Feature Approval Process](#concept--feature-approval-process)
|
||||
* [Strategy Discovery](#strategy-discovery)
|
||||
* [Concept Approval](#concept-approval)
|
||||
* [Time Bound Period](#time-bound-period)
|
||||
* [Approval Committee & Decision Making](#approval-committee--decision-making)
|
||||
* [Committee Members](#committee-members)
|
||||
* [Committee Criteria](#committee-criteria)
|
||||
* [Implementation & Release Approval](#implementation--release-approval)
|
||||
|
||||
Thank you for considering making contributions to the Cosmos SDK and related repositories!
|
||||
|
||||
@@ -23,13 +30,11 @@ discussion or proposing code changes. To ensure a smooth workflow for all
|
||||
contributors, the general procedure for contributing has been established:
|
||||
|
||||
1. Start by browsing [new issues](https://github.com/cosmos/cosmos-sdk/issues) and [discussions](https://github.com/cosmos/cosmos-sdk/discussions). If you are looking for something interesting or if you have something in your mind, there is a chance it was has been discussed.
|
||||
|
||||
- Looking for a good place to start contributing? How about checking out some [good first issues](https://github.com/cosmos/cosmos-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)?
|
||||
|
||||
* Looking for a good place to start contributing? How about checking out some [good first issues](https://github.com/cosmos/cosmos-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)?
|
||||
2. Determine whether a GitHub issue or discussion is more appropriate for your needs:
|
||||
1. If want to propose something new that requires specification or an additional design, or you would like to change a process, start with a [new discussion](https://github.com/cosmos/cosmos-sdk/discussions/new). With discussions, we can better handle the design process using discussion threads. A discussion usually leads to one or more issues.
|
||||
2. If the issue you want addressed is a specific proposal or a bug, then open a [new issue](https://github.com/cosmos/cosmos-sdk/issues/new/choose).
|
||||
3. Review existing [issues](https://github.com/cosmos/cosmos-sdk/issues) to find an issue you'd like to help with.
|
||||
1. If want to propose something new that requires specification or an additional design, or you would like to change a process, start with a [new discussion](https://github.com/cosmos/cosmos-sdk/discussions/new). With discussions, we can better handle the design process using discussion threads. A discussion usually leads to one or more issues.
|
||||
2. If the issue you want addressed is a specific proposal or a bug, then open a [new issue](https://github.com/cosmos/cosmos-sdk/issues/new/choose).
|
||||
3. Review existing [issues](https://github.com/cosmos/cosmos-sdk/issues) to find an issue you'd like to help with.
|
||||
3. Participate in thoughtful discussion on that issue.
|
||||
4. If you would like to contribute:
|
||||
1. Ensure that the proposal has been accepted.
|
||||
@@ -55,10 +60,10 @@ The important development announcements are shared on [Discord](https://discord.
|
||||
|
||||
To synchronize we have few major meetings:
|
||||
|
||||
+ Architecture calls: bi-weekly on Fridays at 14:00 UTC (alternating with the grooming meeting below).
|
||||
+ Grooming / Planning: bi-weekly on Fridays at 14:00 UTC (alternating with the architecture meeting above).
|
||||
+ Cosmos Community SDK Development Call on the last Wednesday of every month at 17:00 UTC.
|
||||
+ Cosmos Roadmap Prioritization every 4 weeks on Tuesday at 15:00 UTC (limited participation).
|
||||
* Architecture calls: bi-weekly on Fridays at 14:00 UTC (alternating with the grooming meeting below).
|
||||
* Grooming / Planning: bi-weekly on Fridays at 14:00 UTC (alternating with the architecture meeting above).
|
||||
* Cosmos Community SDK Development Call on the last Wednesday of every month at 17:00 UTC.
|
||||
* Cosmos Roadmap Prioritization every 4 weeks on Tuesday at 15:00 UTC (limited participation).
|
||||
|
||||
If you would like to join one of those calls, then please contact us on [Discord](https://discord.com/invite/cosmosnetwork) or reach out directly to Cory Levinson from Regen Network (cory@regen.network).
|
||||
|
||||
@@ -68,22 +73,22 @@ When proposing an architecture decision for the Cosmos SDK, please start by open
|
||||
|
||||
## Development Procedure
|
||||
|
||||
- The latest state of development is on `master`.
|
||||
- `master` must never fail `make lint test test-race`.
|
||||
- No `--force` onto `master` (except when reverting a broken commit, which should seldom happen).
|
||||
- Create a branch to start a wok:
|
||||
- Fork the repo (core developers must create a branch directly in the Cosmos SDK repo),
|
||||
* The latest state of development is on `master`.
|
||||
* `master` must never fail `make lint test test-race`.
|
||||
* No `--force` onto `master` (except when reverting a broken commit, which should seldom happen).
|
||||
* Create a branch to start a wok:
|
||||
* Fork the repo (core developers must create a branch directly in the Cosmos SDK repo),
|
||||
branch from the HEAD of `master`, make some commits, and submit a PR to `master`.
|
||||
- For core developers working within the `cosmos-sdk` repo, follow branch name conventions to ensure a clear
|
||||
* For core developers working within the `cosmos-sdk` repo, follow branch name conventions to ensure a clear
|
||||
ownership of branches: `{moniker}/{issue#}-branch-name`.
|
||||
- See [Branching Model](#branching-model-and-release) for more details.
|
||||
- Be sure to run `make format` before every commit. The easiest way
|
||||
* See [Branching Model](#branching-model-and-release) for more details.
|
||||
* Be sure to run `make format` before every commit. The easiest way
|
||||
to do this is have your editor run it for you upon saving a file (most of the editors
|
||||
will do it anyway using a pre-configured setup of the programming language mode).
|
||||
Additionally, be sure that your code is lint compliant by running `make lint-fix`.
|
||||
A convenience git `pre-commit` hook that runs the formatters automatically
|
||||
before each commit is available in the `contrib/githooks/` directory.
|
||||
- Follow the [CODING GUIDELINES](CODING_GUIDELINES.md), which defines criteria for designing and coding a software.
|
||||
* Follow the [CODING GUIDELINES](CODING_GUIDELINES.md), which defines criteria for designing and coding a software.
|
||||
|
||||
Code is merged into master through pull request procedure.
|
||||
|
||||
@@ -95,8 +100,8 @@ Tests can be executed by running `make test` at the top level of the Cosmos SDK
|
||||
|
||||
Before submitting a pull request:
|
||||
|
||||
- merge the latest master `git merge origin/master`,
|
||||
- run `make lint test` to ensure that all checks and tests pass.
|
||||
* merge the latest master `git merge origin/master`,
|
||||
* run `make lint test` to ensure that all checks and tests pass.
|
||||
|
||||
Then:
|
||||
|
||||
@@ -120,8 +125,8 @@ NOTE: when merging, GitHub will squash commits and rebase on top of the master.
|
||||
|
||||
There are three PR templates. The [default template](./.github/PULL_REQUEST_TEMPLATE.md) is for types `fix`, `feat`, and `refactor`. We also have a [docs template](./.github/PULL_REQUEST_TEMPLATE/docs.md) for documentation changes and an [other template](./.github/PULL_REQUEST_TEMPLATE/other.md) for changes that do not affect production code. When previewing a PR before it has been opened, you can change the template by adding one of the following parameters to the url:
|
||||
|
||||
- `template=docs.md`
|
||||
- `template=other.md`
|
||||
* `template=docs.md`
|
||||
* `template=other.md`
|
||||
|
||||
### Requesting Reviews
|
||||
|
||||
@@ -138,24 +143,24 @@ the case of minor changes to [docs](./.github/PULL_REQUEST_TEMPLATE/docs.md) or
|
||||
for all checked items unless they have indicated otherwise by leaving their handle next to specific
|
||||
items. In addition, use the following review explanations:
|
||||
|
||||
- `LGTM` without an explicit approval means that the changes look good, but you haven't thoroughly reviewed the reviewer checklist items.
|
||||
- `Approval` means that you have completed some or all of the reviewer checklist items. If you only reviewed selected items, you must add your handle next to the items that you have reviewed. In addition, follow these guidelines:
|
||||
- You must also think through anything which ought to be included but is not
|
||||
- You must think through whether any added code could be partially combined (DRYed) with existing code
|
||||
- You must think through any potential security issues or incentive-compatibility flaws introduced by the changes
|
||||
- Naming must be consistent with conventions and the rest of the codebase
|
||||
- Code must live in a reasonable location, considering dependency structures (for example, not importing testing modules in production code, or including example code modules in production code).
|
||||
- If you approve the PR, you are responsible for any issues mentioned here and any issues that should have been addressed after thoroughly reviewing the reviewer checklist items in the pull request template.
|
||||
- If you sat down with the PR submitter and did a pairing review, add this information in the `Approval` or your PR comments.
|
||||
- If you are only making "surface level" reviews, submit notes as a `comment` review.
|
||||
* `LGTM` without an explicit approval means that the changes look good, but you haven't thoroughly reviewed the reviewer checklist items.
|
||||
* `Approval` means that you have completed some or all of the reviewer checklist items. If you only reviewed selected items, you must add your handle next to the items that you have reviewed. In addition, follow these guidelines:
|
||||
* You must also think through anything which ought to be included but is not
|
||||
* You must think through whether any added code could be partially combined (DRYed) with existing code
|
||||
* You must think through any potential security issues or incentive-compatibility flaws introduced by the changes
|
||||
* Naming must be consistent with conventions and the rest of the codebase
|
||||
* Code must live in a reasonable location, considering dependency structures (for example, not importing testing modules in production code, or including example code modules in production code).
|
||||
* If you approve the PR, you are responsible for any issues mentioned here and any issues that should have been addressed after thoroughly reviewing the reviewer checklist items in the pull request template.
|
||||
* If you sat down with the PR submitter and did a pairing review, add this information in the `Approval` or your PR comments.
|
||||
* If you are only making "surface level" reviews, submit notes as a `comment` review.
|
||||
|
||||
### Updating Documentation
|
||||
|
||||
If you open a PR on the Cosmos SDK, it is mandatory to update the relevant documentation in `/docs`.
|
||||
|
||||
- If your change relates to the core SDK (baseapp, store, ...), be sure to update the content in `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders.
|
||||
- If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), then modify the content in the `docs/run-node/` folder.
|
||||
- If your changes relate to a module, then be sure to update the module's spec in `x/moduleName/docs/spec/`.
|
||||
* If your change relates to the core SDK (baseapp, store, ...), be sure to update the content in `docs/basics/`, `docs/core/` and/or `docs/building-modules/` folders.
|
||||
* If your changes relate to the core of the CLI (not specifically to module's CLI/Rest), then modify the content in the `docs/run-node/` folder.
|
||||
* If your changes relate to a module, then be sure to update the module's spec in `x/moduleName/docs/spec/`.
|
||||
|
||||
When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md).
|
||||
|
||||
@@ -189,7 +194,7 @@ In order for imports to properly compile in your IDE, you may need to manually s
|
||||
|
||||
For example, in vscode your `.vscode/settings.json` should look like:
|
||||
|
||||
```
|
||||
```json
|
||||
{
|
||||
"protoc": {
|
||||
"options": [
|
||||
@@ -202,7 +207,7 @@ For example, in vscode your `.vscode/settings.json` should look like:
|
||||
|
||||
## Branching Model and Release
|
||||
|
||||
User-facing repos should adhere to the trunk based development branching model: https://trunkbaseddevelopment.com/. User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`.
|
||||
User-facing repos should adhere to the trunk based development branching model: <https://trunkbaseddevelopment.com/>. User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`.
|
||||
|
||||
The Cosmos SDK repository is a [multi Go module](https://github.com/golang/go/wiki/Modules#is-it-possible-to-add-a-module-to-a-multi-module-repository) repository. It means that we have more than one Go module in a single repository.
|
||||
|
||||
@@ -272,7 +277,7 @@ is broken up into three distinct stages: **Strategy Discovery**, **Concept Appro
|
||||
* After proposal, a time bound period for Request for Comment (RFC) on ADRs commences
|
||||
* ADRs are intended to be iterative, and may be merged into `master` while still in a `Proposed` status
|
||||
|
||||
**Time Bound Period**
|
||||
#### Time Bound Period
|
||||
|
||||
* Once a PR for an ADR is opened, reviewers are expected to perform a first
|
||||
review within 1 week of pull request being open
|
||||
@@ -286,20 +291,20 @@ the current state of its discussion.
|
||||
If an ADR is taking longer than 4 weeks to reach a final conclusion, the **Concept Approval Committee**
|
||||
should convene to rectify the situation by either:
|
||||
|
||||
- unanimously setting a new time bound period for this ADR
|
||||
- making changes to the Concept Approval Process (as outlined here)
|
||||
- making changes to the members of the Concept Approval Committee
|
||||
* unanimously setting a new time bound period for this ADR
|
||||
* making changes to the Concept Approval Process (as outlined here)
|
||||
* making changes to the members of the Concept Approval Committee
|
||||
|
||||
**Approval Committee & Decision Making**
|
||||
#### Approval Committee & Decision Making
|
||||
|
||||
In absence of general consensus, decision making requires 1/2 vote from the two members
|
||||
of the **Concept Approval Committee**.
|
||||
|
||||
**Committee Members**
|
||||
#### Committee Members
|
||||
|
||||
* Core Members: **Aaron** (Regen), **Bez** (IG)
|
||||
|
||||
**Committee Criteria**
|
||||
#### Committee Criteria
|
||||
|
||||
Members must:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user