docs: add documentation on documentation deployment (#13739)
This commit is contained in:
Julien Robert
GitHub
parent
9b8e1a18b9
commit
0e421d8295
11
.github/CODEOWNERS
vendored
11
.github/CODEOWNERS
vendored
@ -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
|
||||
|
||||
18
CHANGELOG.md
18
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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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).
|
||||
|
||||
## 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 the following stack:
|
||||
|
||||
* [Docusaurus 2](https://docusaurus.io)
|
||||
* Vuepress (pre v0.47)
|
||||
* [Algolia DocSearch](https://docsearch.algolia.com/)
|
||||
|
||||
```js
|
||||
algolia: {
|
||||
appId: "QLS2QSP47E",
|
||||
apiKey: "067b84458bfa80c295e1d4f12c461911",
|
||||
indexName: "cosmos_network",
|
||||
contextualSearch: false,
|
||||
},
|
||||
```
|
||||
|
||||
* GitHub Pages
|
||||
|
||||
## Docs Build Workflow
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
## README
|
||||
## How to Build the Docs Locally
|
||||
|
||||
The [README.md](./README.md) is both the README for the repository and the configuration for the layout of the landing page.
|
||||
|
||||
## 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 versionning.
|
||||
Note that in case of page reshufling, you must update all links references.
|
||||
|
||||
### Full
|
||||
|
||||
The full GitHub URL to a file or directory. Used occasionally when it makes sense
|
||||
to send users to the GitHub.
|
||||
|
||||
## Building Locally
|
||||
|
||||
Make sure you are in the `docs` directory and run the following commands:
|
||||
|
||||
```shell
|
||||
rm -rf node_modules
|
||||
```
|
||||
|
||||
This command will remove old version of the visual theme and required packages. This step is optional.
|
||||
Go to the `docs` directory and run the following commands:
|
||||
|
||||
```shell
|
||||
cd docs
|
||||
npm install
|
||||
```
|
||||
|
||||
Install the theme and all dependencies.
|
||||
For starting only the current documentation, run:
|
||||
|
||||
```shell
|
||||
npm start
|
||||
```
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
To build documentation as a static website run `npm run build`.
|
||||
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.
|
||||
|
||||
## Search
|
||||
To build all the docs (including versioned documentation), run:
|
||||
|
||||
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.
|
||||
```shell
|
||||
make build-docs
|
||||
```
|
||||
|
||||
## 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`.
|
||||
|
||||
```js
|
||||
{
|
||||
from: ["/", "/master", "/v0.43", "/v0.44", "/v0.XX"], // here add the deprecated version
|
||||
to: "/main",
|
||||
},
|
||||
```
|
||||
|
||||
* Add the new version sidebar to the list of versionned sidebar and add the version to `versions`
|
||||
|
||||
Learn more about [versioning](https://docusaurus.io/docs/versioning) in Docusaurus.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user