From 0e421d8295ca6d1dfb2ccd1be25e2328106acc14 Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Thu, 3 Nov 2022 17:23:52 +0100 Subject: [PATCH] docs: add documentation on documentation deployment (#13739) --- .github/CODEOWNERS | 11 ++++- CHANGELOG.md | 18 ++++---- RELEASE_PROCESS.md | 29 +++++++------ docs/DOC_WRITING_GUIDELINES.md | 25 +++++++++++ docs/README.md | 78 ++++++++++++++++++++++------------ 5 files changed, 108 insertions(+), 53 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 4b9db54900af..59a1be47b7f9 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,7 +1,14 @@ # CODEOWNERS: https://help.github.com/articles/about-codeowners/ -# NOTE: Order is important; the last matching pattern takes the -# most precedence. +# NOTE: Order is important; the last matching pattern takes the most precedence # Primary repo maintainers + * @cosmos/sdk-core-dev + +# CODEOWNERS for docs configuration + +/docs/docusaurus.config.js @julienrbrt @tac0turtle +/docs/sidebars.js @julienrbrt @tac0turtle +/docs/pre.sh @julienrbrt @tac0turtle +/docs/post.sh @julienrbrt @tac0turtle diff --git a/CHANGELOG.md b/CHANGELOG.md index a3053a2f5b65..9931e9ea6e71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,12 +75,12 @@ Ref: https://keepachangelog.com/en/1.0.0/ * [#12634](https://github.com/cosmos/cosmos-sdk/pull/12634) Move `sdk.Dec` to math package. * [#12596](https://github.com/cosmos/cosmos-sdk/pull/12596) Remove all imports of the non-existent gogo/protobuf v1.3.3 to ease downstream use and go workspaces. * [#12187](https://github.com/cosmos/cosmos-sdk/pull/12187) Add batch operation for x/nft module. -* [#12455](https://github.com/cosmos/cosmos-sdk/pull/12455) Show attempts count in error for signing. +* [#12455](https://github.com/cosmos/cosmos-sdk/pull/12455) Show attempts count in error for signing. * [#13101](https://github.com/cosmos/cosmos-sdk/pull/13101) Remove weights from `simapp/params` and `testutil/sims`. They are now in their respective modules. * [#12398](https://github.com/cosmos/cosmos-sdk/issues/12398) Refactor all `x` modules to unit-test via mocks and decouple `simapp`. * [#13144](https://github.com/cosmos/cosmos-sdk/pull/13144) Add validator distribution info grpc gateway get endpoint. * [#13168](https://github.com/cosmos/cosmos-sdk/pull/13168) Migrate tendermintdev/proto-builder to ghcr.io. New image `ghcr.io/cosmos/proto-builder:0.8` -* [#13178](https://github.com/cosmos/cosmos-sdk/pull/13178) Add `cosmos.msg.v1.service` protobuf annotation to allow tooling to distinguish between Msg and Query services via reflection. +* [#13178](https://github.com/cosmos/cosmos-sdk/pull/13178) Add `cosmos.msg.v1.service` protobuf annotation to allow tooling to distinguish between Msg and Query services via reflection. * [#13236](https://github.com/cosmos/cosmos-sdk/pull/13236) Integrate Filter Logging * [#13528](https://github.com/cosmos/cosmos-sdk/pull/13528) Update `ValidateMemoDecorator` to only check memo against `MaxMemoCharacters` param when a memo is present. * [#13651](https://github.com/cosmos/cosmos-sdk/pull/13651) Update `server/config/config.GetConfig` function. @@ -150,7 +150,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (x/genutil)[#12956](https://github.com/cosmos/cosmos-sdk/pull/12956) `genutil.AppModuleBasic` has a new attribute: genesis transaction validation function. The existing validation logic is implemented in `genutiltypes.DefaultMessageValidator`. Use `genutil.NewAppModuleBasic` to create a new genutil Module Basic. * (codec) [#12964](https://github.com/cosmos/cosmos-sdk/pull/12964) `ProtoCodec.MarshalInterface` now returns an error when serializing unregistered types and a subsequent `ProtoCodec.UnmarshalInterface` would fail. * (x/staking) [#12973](https://github.com/cosmos/cosmos-sdk/pull/12973) Removed `stakingkeeper.RandomValidator`. Use `testutil.RandSliceElem(r, sk.GetAllValidators(ctx))` instead. -* (x/gov) [#13160](https://github.com/cosmos/cosmos-sdk/pull/13160) Remove custom marshaling of proposl and voteoption. +* (x/gov) [#13160](https://github.com/cosmos/cosmos-sdk/pull/13160) Remove custom marshaling of proposl and voteoption. * (types) [#13430](https://github.com/cosmos/cosmos-sdk/pull/13430) Remove unused code `ResponseCheckTx` and `ResponseDeliverTx` * (store) [#13529](https://github.com/cosmos/cosmos-sdk/pull/13529) Add method `LatestVersion` to `MultiStore` interface, add method `SetQueryMultiStore` to baesapp to support alternative `MultiStore` implementation for query service. * (pruning) [#13609]](https://github.com/cosmos/cosmos-sdk/pull/13609) Move pruning pacakge to be under store pacakge @@ -211,7 +211,7 @@ Ref: https://keepachangelog.com/en/1.0.0/ ATTENTION: -This is a security release for the [Dragonberry security advisory](https://forum.cosmos.network/t/ibc-security-advisory-dragonberry/7702). +This is a security release for the [Dragonberry security advisory](https://forum.cosmos.network/t/ibc-security-advisory-dragonberry/7702). All users should upgrade immediately. @@ -268,7 +268,7 @@ replace github.com/confio/ics23/go => github.com/cosmos/cosmos-sdk/ics23/go v0.8 * (x/auth) [#13048](https://github.com/cosmos/cosmos-sdk/pull/13048) Add handling of AccountNumberStoreKeyPrefix to the simulation decoder. * (simapp) [#13107](https://github.com/cosmos/cosmos-sdk/pull/13107) Call `SetIAVLCacheSize` with the configured value in simapp. * [#13301](https://github.com/cosmos/cosmos-sdk/pull/13301) Keep the balance query endpoint compatible with legacy blocks -* [#13321](https://github.com/cosmos/cosmos-sdk/pull/13321) Add flag to disable fast node migration and usage. +* [#13321](https://github.com/cosmos/cosmos-sdk/pull/13321) Add flag to disable fast node migration and usage. ### Bug Fixes @@ -607,7 +607,7 @@ replace github.com/confio/ics23/go => github.com/cosmos/cosmos-sdk/ics23/go v0.8 ATTENTION: -This is a security release for the [Dragonberry security advisory](https://forum.cosmos.network/t/ibc-security-advisory-dragonberry/7702). +This is a security release for the [Dragonberry security advisory](https://forum.cosmos.network/t/ibc-security-advisory-dragonberry/7702). All users should upgrade immediately. @@ -627,7 +627,7 @@ replace github.com/confio/ics23/go => github.com/cosmos/cosmos-sdk/ics23/go v0.8 * [#13323](https://github.com/cosmos/cosmos-sdk/pull/13323) Ensure `withdraw_rewards` rewards are emitted from all actions that result in rewards being withdrawn. * [#13321](https://github.com/cosmos/cosmos-sdk/pull/13321) Add flag to disable fast node migration and usage. * (store) [#13326](https://github.com/cosmos/cosmos-sdk/pull/13326) Implementation of ADR-038 file StreamingService, backport #8664. -* (store) [#13540](https://github.com/cosmos/cosmos-sdk/pull/13540) Default fastnode migration to false to prevent suprises. Operators must enable it, unless they have it enabled already. +* (store) [#13540](https://github.com/cosmos/cosmos-sdk/pull/13540) Default fastnode migration to false to prevent suprises. Operators must enable it, unless they have it enabled already. ### API Breaking Changes @@ -870,7 +870,7 @@ empty coins slice before it is used to create `banktype.MsgSend`. ATTENTION: -This is a security release for the [Dragonberry security advisory](https://forum.cosmos.network/t/ibc-security-advisory-dragonberry/7702). +This is a security release for the [Dragonberry security advisory](https://forum.cosmos.network/t/ibc-security-advisory-dragonberry/7702). All users should upgrade immediately. @@ -1744,7 +1744,7 @@ sure you are aware of any relevant breaking changes. * (types/rest) [#5900](https://github.com/cosmos/cosmos-sdk/pull/5900) Add Check\*Error function family to spare developers from replicating tons of boilerplate code. * (types) [#6128](https://github.com/cosmos/cosmos-sdk/pull/6137) Add `String()` method to `GasMeter`. * (types) [#6195](https://github.com/cosmos/cosmos-sdk/pull/6195) Add codespace to broadcast(sync/async) response. - * (types) \#6897 Add KV type from tendermint to `types` directory. + * (types) [#6897](https://github.com/cosmos/cosmos-sdk/issues/6897) Add KV type from tendermint to `types` directory. * (version) [#7848](https://github.com/cosmos/cosmos-sdk/pull/7848) [#7941](https://github.com/cosmos/cosmos-sdk/pull/7941) `version --long` output now shows the list of build dependencies and replaced build dependencies. diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 340664a6d350..d3fae1755c8b 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -4,7 +4,7 @@ This document outlines the process for releasing a new version of Cosmos SDK, wh ## Major Release Procedure -A _major release_ is an increment of the first number (eg: `v1.2` → `v2.0.0`) or the _point number_ (eg: `v1.1 → v1.2.0`, also called _point release_). Each major release opens a _stable release series_ and receives updates outlined in the [Major Release Maintenance](#major-release-maintenance)_section. +A _major release_ is an increment of the first number (eg: `v1.2` → `v2.0.0`) or the _point number_ (eg: `v1.1.0 → v1.2.0`, also called _point release_). Each major release opens a _stable release series_ and receives updates outlined in the [Major Release Maintenance](#major-release-maintenance)_section. Before making a new _major_ release we do beta and release candidate releases. For example, for release 1.0.0: @@ -21,10 +21,11 @@ v1.0.0-beta1 → v1.0.0-beta2 → ... → v1.0.0-rc1 → v1.0.0-rc2 → ... → * After the team feels that the `main` works fine we create a `release/vY` branch (going forward known a release branch), where `Y` is the version number, with the patch part substituted to `x` (eg: 0.42.x, 1.0.x). Ensure the release branch is protected so that pushes against the release branch are permitted only by the release manager or release coordinator. * **PRs targeting this branch can be merged _only_ when exceptional circumstances arise** * update the GitHub mergify integration by adding instructions for automatically backporting commits from `main` to the `release/vY` using the `backport/Y` label. -* In the release branch, prepare a new version section in the `CHANGELOG.md` +* In the release branch prepare a new version section in the `CHANGELOG.md` * All links must be link-ified: `$ python ./scripts/linkify_changelog.py CHANGELOG.md` - * Copy the entries into a `RELEASE_CHANGELOG.md`, this is needed so the bot knows which entries to add to the release page on GitHub. -* Create a new annotated git tag for a release candidate (eg: `git tag -a v1.1.0-rc1`) in the release branch. + * Create release notes, in `RELEASE_NOTES.md`, highlighting the changes and how to upgrade the SDK. This is needed so the bot knows which entries to add to the release page on GitHub. +* Remove GitHub workflows that should not be in the release branch (eg: `deploy-docs.yml`). +* Create a new annotated git tag for a release candidate (eg: `git tag -a v1.1.0-rc1`) in the release branch. * from this point we unfreeze main. * the SDK teams collaborate and do their best to run testnets in order to validate the release. * when bugs are found, create a PR for `main`, and backport fixes to the release branch. @@ -58,9 +59,11 @@ Point Release must follow the [Stable Release Policy](#stable-release-policy). After the release branch has all commits required for the next patch release: -* update `CHANGELOG.md`. -* create a new annotated git tag (eg `git -a v1.1.0`) in the release branch. -* Create a GitHub release. +* Update `CHANGELOG.md` and `RELEASE_NOTES.md` (if applicable). +* Create a new annotated git tag (eg `git -a v1.1.0`) in the release branch. + * If the release is a submodule update, first go the submodule folder and name the tag prepending the path to the version: + `cd core && git -a core/v1.1.0` or `cd tools/cosmovisor && git -a tools/cosmovisor/v1.4.0` +* Create a GitHub release (if applicable). ## Major Release Maintenance @@ -70,16 +73,16 @@ Note: not every Major Release is denoted as stable releases. Only the following major release series have a stable release status: -* **0.42 «Stargate»** is supported until 2022-02-09. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a stable point-release. -* **0.44** is supported until 2022-07-17. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a stable point-release. -* **0.45** is the latest major release and will be supported until 6 months after **0.46.0** release. +* **0.45** is supported until 6 months after **0.46.0** release. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a stable point-release. +* **0.46** is the last major release and will be supportted until 6 months after **0.47.0** release. +* **0.47** is the next major release and will be supported until 6 months after **0.48.0** release. ## Stable Release Policy ### Patch Releases Once a Cosmos-SDK release has been completed and published, updates for it are released under certain circumstances -and must follow the [Patch Release Procedure][CONTRIBUTING.md#patch-release-procedure](Point Release Procedure). +and must follow the [Patch Release Procedure](CONTRIBUTING.md#branching-model-and-release). ### Rationale @@ -188,7 +191,7 @@ It's crucial to make the effort of thinking about what could happen in case a re ### Stable Release Managers The **Stable Release Managers** evaluate and approve or reject updates and backports to Cosmos-SDK Stable Release series, -according to the [stable release policy](#stable-release-policy) and [release procedure](#stable-release-exception-procedure). +according to the [stable release policy](#stable-release-policy) and [release procedure](#major-release-procedure). Decisions are made by consensus. Their responsibilites include: @@ -199,6 +202,4 @@ Their responsibilites include: The Stable Release Managers are appointed by the Interchain Foundation. Currently residing Stable Release Managers: -* @clevinson - Cory Levinson * @amaurym - Amaury Martiny -* @robert-zaremba - Robert Zaremba diff --git a/docs/DOC_WRITING_GUIDELINES.md b/docs/DOC_WRITING_GUIDELINES.md index ebedb46ad6b0..2f40bd47708b 100644 --- a/docs/DOC_WRITING_GUIDELINES.md +++ b/docs/DOC_WRITING_GUIDELINES.md @@ -10,6 +10,31 @@ * 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!). * RFC keywords should be used in technical documents (uppercase) and we recommend to use them in user documentation (lowercase). The RFC keywords are: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). +### Links + +**NOTE:** Strongly consider the existing links - both within this directory and to the website docs - when moving or deleting files. + +Relative links should be used nearly everywhere, due to versioning. Note that in case of page reshuffling, you must update all links references. +When deleting a link, redirects must be created in `docusaurus.config.js` to preserve the user flow. + +### Code Snippets + +Code snippets can be included in the documentation using normal Markdown code blocks. For example: + +```md + ```go + func() {} + ``` +``` + +It is also possible to include code snippets from GitHub files by referencing the files directly (and the line numbers if needed). For example: + +```md + ```go reference + https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/server/types/app.go#L57-L59 + ``` +``` + ## Technical Writing Course Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing. diff --git a/docs/README.md b/docs/README.md index d2cb8e73c1d9..020a97937493 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,57 +1,79 @@ # Updating the docs -If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation). +If you want to open a PR in Cosmos SDK to update the documentation, please follow the guidelines in [`CONTRIBUTING.md`](https://github.com/cosmos/cosmos-sdk/tree/main/CONTRIBUTING.md#updating-documentation) and the [Documentation Writing Guidelines](./DOC_WRITING_GUIDELINES.md). -## Docs Build Workflow +## Stack The documentation for Cosmos SDK is hosted at https://docs.cosmos.network and built from the files in the `/docs` directory. -It is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. - -### How It Works - -There is a GitHub Action listening for changes in the `/docs` directory for the `main` branch and each supported version branch (e.g. `release/v0.46.x`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a Github Action within that repository. +It is built using the following stack: -## README +* [Docusaurus 2](https://docusaurus.io) +* Vuepress (pre v0.47) +* [Algolia DocSearch](https://docsearch.algolia.com/) -The [README.md](./README.md) is both the README for the repository and the configuration for the layout of the landing page. + ```js + algolia: { + appId: "QLS2QSP47E", + apiKey: "067b84458bfa80c295e1d4f12c461911", + indexName: "cosmos_network", + contextualSearch: false, + }, + ``` -## Links +* GitHub Pages -**NOTE:** Strongly consider the existing links - both within this directory -and to the website docs - when moving or deleting files. +## Docs Build Workflow -Relative links should be used nearly everywhere, due to versionning. -Note that in case of page reshufling, you must update all links references. +The docs are built and deployed automatically on GitHub Pages by a [GitHub Action workflow](../.github/workflows/deploy-docs.yml). +The workflow is triggered on every push to the `main` and `release/v**` branches, every time documentations or specs are modified. -### Full +### How It Works -The full GitHub URL to a file or directory. Used occasionally when it makes sense -to send users to the GitHub. +There is a GitHub Action listening for changes in the `/docs` directory for the `main` branch and each supported version branch (e.g. `release/v0.46.x`). Any updates to files in the `/docs` directory will automatically trigger a website deployment. Under the hood, the private website repository has a `make build-docs` target consumed by a Github Action within that repository. -## Building Locally +## How to Build the Docs Locally -Make sure you are in the `docs` directory and run the following commands: +Go to the `docs` directory and run the following commands: ```shell -rm -rf node_modules +cd docs +npm install ``` -This command will remove old version of the visual theme and required packages. This step is optional. +For starting only the current documentation, run: ```shell -npm install +npm start ``` -Install the theme and all dependencies. +It runs `pre.sh` scripts to get all the docs that are not already in the `docs/docs` folder. +It also runs `post.sh` scripts to clean up the docs and remove unnecessary files when quitting. + +Note, the command above only build the docs for the current versions. +With the drawback that none of the redirections works. So, you'll need to go to /main to see the docs. + +To build all the docs (including versioned documentation), run: ```shell -npm start +make build-docs ``` -Run `pre` and `post` hooks and start a hot-reloading web-server. See output of this command for the URL (it is often https://localhost:3000). +## What to for new major SDK versions + +When a new major version of the SDK is released, the following steps should be taken: + +* On the `release/vX.Y.Z` branch, remove the deploy action (`.github/workflows/deploy-docs.yml`), for avoiding deploying the docs from the release branches +* Each time a new version is released (on docusaurus), drop support from the oldest versions. + * If the old version is still running vuepress (v0.45, v0.46), remove its line from `vuepress_versions` + * If any, remove the outdated redirections from `docusaurus.config.js` and add the base version redirection (`/vX.XX`) to `/main`. -To build documentation as a static website run `npm run build`. + ```js + { + from: ["/", "/master", "/v0.43", "/v0.44", "/v0.XX"], // here add the deprecated version + to: "/main", + }, + ``` -## Search +* Add the new version sidebar to the list of versionned sidebar and add the version to `versions` -We are using [Algolia](https://www.algolia.com) to power full-text search. This uses a public API search-only key in the `config.js` as well as a [cosmos_network.json](https://github.com/algolia/docsearch-configs/blob/master/configs/cosmos_network.json) configuration file that we can update with PRs. \ No newline at end of file +Learn more about [versioning](https://docusaurus.io/docs/versioning) in Docusaurus.