diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe139c23b206..0a814148197c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -97,6 +97,8 @@ If you open a PR on the Cosmos SDK, it is mandatory to update the relevant docum - If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the `docs/interfaces/` folder. - If your changes relate to a module, please update the module's spec in `x/moduleName/docs/spec/`. +When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md). + ## Forking Please note that Go requires code to live under absolute paths, which complicates forking. @@ -166,7 +168,7 @@ For example, in vscode your `.vscode/settings.json` should look like: ## Testing -Tests can be ran by running `make test` at the top level of the SDK repository. +Tests can be ran by running `make test` at the top level of the SDK repository. We expect tests to use `require` or `assert` rather than `t.Skip` or `t.Fail`, unless there is a reason to do otherwise. @@ -204,7 +206,7 @@ The SDK utilizes [semantic versioning](https://semver.org/). Ensure that you base and target your PR on the `master` branch. All feature additions should be targeted against `master`. Bug fixes for an outstanding release candidate -should be targeted against the release candidate branch. +should be targeted against the release candidate branch. ### Development Procedure @@ -324,7 +326,7 @@ the community of this project. ## Concept & Release Approval Process The process for how Cosmos SDK maintainers take features and ADRs from concept to release -is broken up into three distinct stages: **Strategy Discovery**, **Concept Approval**, and +is broken up into three distinct stages: **Strategy Discovery**, **Concept Approval**, and **Implementation & Release Approval** @@ -352,7 +354,7 @@ If an individual Pull Request for an ADR needs more time than 2 weeks to reach r in current state (`Draft` or `Proposed`), with its contents updated to summarize the current state of its discussion. -If an ADR is taking longer than 4 weeks to reach a final conclusion, the **Concept Approval Committee** +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) @@ -396,7 +398,7 @@ well as for PRs made as part of a release process: * Code reviewers should ensure the PR does exactly what the ADR said it should * Code reviewers should have more senior engineering capability * 1/2 approval is required from the **primary repo maintainers** in `CODEOWNERS` - + *Note: For any major or minor release series denoted as a "Stable Release" (e.g. v0.39 "Launchpad"), a separate release committee is often established. Stable Releases, and their corresponding release committees are documented separately in [STABLE_RELEASES.md](./STABLE_RELEASES.md)* diff --git a/docs/DOC_WRITING_GUIDELINES.md b/docs/DOC_WRITING_GUIDELINES.md new file mode 100644 index 000000000000..cf5b809a0bcf --- /dev/null +++ b/docs/DOC_WRITING_GUIDELINES.md @@ -0,0 +1,16 @@ +# Documentation Writing Guidelines + +## Best Practices + ++ Check the spelling and grammar, even if you have to copy and paste from an external source. ++ Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. ++ Try to express your thoughts in a concise and clean way. ++ Don't abuse `code` format when writing in plain English. ++ Follow Google developer documentation [style guide](https://developers.google.com/style). ++ Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!). + + + +## Technical Writing Course + +Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing.