From c9a3831328d573785c9cef82253afdde6fc032ae Mon Sep 17 00:00:00 2001 From: MSalopek Date: Tue, 14 May 2024 12:43:53 +0200 Subject: [PATCH] docs: add docs versioning (#3092) * docs: add versioning for current docs * docs: mv archived migrations; mv modules * docs: update docusaurus configs * docs: update docusaurus configs * rm unneded file; update docs docs * update docusaurus * Update DOCS_README.md --- docs/DOCS_README.md | 15 +- docs/README copy.md | 40 ---- docs/docs/index.mdx | 6 +- docs/docs/interchain-security/README.md | 4 +- docs/docs/metaprotocols/_category_.json | 5 - docs/docs/migration/README.md | 18 +- docs/docs/migration/_category_.json | 2 +- docs/docs/migration/archive/README.md | 16 ++ .../{ => archive}/cosmoshub-2/_category_.json | 0 .../{ => archive}/cosmoshub-2/cosmoshub-2.md | 0 .../{ => archive}/cosmoshub-3/_category_.json | 0 .../{ => archive}/cosmoshub-3/cosmoshub-3.md | 0 .../archive/cosmoshub-4/_category_.json | 5 + .../cosmoshub-4}/cosmoshub-4-v10-upgrade.md | 0 .../cosmoshub-4}/cosmoshub-4-v11-upgrade.md | 0 .../cosmoshub-4}/cosmoshub-4-v12-upgrade.md | 0 .../cosmoshub-4}/cosmoshub-4-v13-upgrade.md | 0 .../cosmoshub-4}/cosmoshub-4-v14-upgrade.md | 2 +- .../cosmoshub-4}/cosmoshub-4-v15-upgrade.md | 2 +- .../cosmoshub-4-v5-delta-upgrade.md | 0 .../cosmoshub-4-v6-vega-upgrade.md | 0 .../cosmoshub-4-v7-Theta-upgrade.md | 0 .../cosmoshub-4-v8-Rho-upgrade.md | 0 .../cosmoshub-4-v9-Lambda-upgrade.md | 0 docs/docs/migration/latest.md | 200 ++++++++++++++++++ docs/docs/modules/README.md | 3 +- docs/docs/modules/globalfee.md | 4 +- .../README.md => modules/metaprotocols.md} | 6 +- docs/docusaurus.config.js | 174 +++++++-------- docs/versions.json | 4 +- 30 files changed, 344 insertions(+), 162 deletions(-) delete mode 100644 docs/README copy.md delete mode 100644 docs/docs/metaprotocols/_category_.json create mode 100644 docs/docs/migration/archive/README.md rename docs/docs/migration/{ => archive}/cosmoshub-2/_category_.json (100%) rename docs/docs/migration/{ => archive}/cosmoshub-2/cosmoshub-2.md (100%) rename docs/docs/migration/{ => archive}/cosmoshub-3/_category_.json (100%) rename docs/docs/migration/{ => archive}/cosmoshub-3/cosmoshub-3.md (100%) create mode 100644 docs/docs/migration/archive/cosmoshub-4/_category_.json rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v10-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v11-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v12-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v13-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v14-upgrade.md (99%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v15-upgrade.md (99%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v5-delta-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v6-vega-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v7-Theta-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v8-Rho-upgrade.md (100%) rename docs/docs/migration/{ => archive/cosmoshub-4}/cosmoshub-4-v9-Lambda-upgrade.md (100%) create mode 100644 docs/docs/migration/latest.md rename docs/docs/{metaprotocols/README.md => modules/metaprotocols.md} (97%) diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 543ffb7168f..0ceca6269ec 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -7,12 +7,6 @@ parent: If you want to open a PR on Gaia to update the documentation, please follow the guidelines in the [`CONTRIBUTING.md`](https://github.com/cosmos/gaia/tree/main/CONTRIBUTING.md) -## Internationalization - -- Translations for documentation live in a `docs/translations//` folder, where `` is the language code for a specific language. For example, `zh` for Chinese, `ko` for Korean, `es` for Spanish, etc. -- Each `docs/translations//` folder must follow the same folder structure within `docs/`, but only content in the following folders needs to be translated and included in the respective `docs/translations//` folder -- Each `docs/translations//` folder must also have a `README.md` that includes a translated version of both the layout and content within the root-level [`README.md`](https://github.com/cosmos/cosmos-sdk/tree/master/docs/README.md). The layout defined in the `README.md` is used to build the homepage. - ## Docs Build Workflow The documentation for Gaia is hosted at: @@ -79,6 +73,15 @@ Install project dependencies npm install ``` +Pull the versions referenced in `versions.json` and `docusaurus.config.js`: + +```shell +cd ../ # back to project root +make build-docs +git checkout +cd docs +``` + Serve the app ```bash diff --git a/docs/README copy.md b/docs/README copy.md deleted file mode 100644 index 420d6daaa1e..00000000000 --- a/docs/README copy.md +++ /dev/null @@ -1,40 +0,0 @@ - - -# Cosmos Hub Documentation - -Welcome to the documentation of the **Cosmos Hub application: `gaia`**. - -## What is Gaia? - -- [Intro to the `gaia` software](./getting-started/what-is-gaia.md) -- [Interacting with the `gaiad` binary](./hub-tutorials/gaiad.md) - -## Join the Cosmos Hub Mainnet - -- [Install the `gaia` application](./getting-started/installation.md) -- [Set up a full node and join the mainnet](./hub-tutorials/join-mainnet.md) -- [Upgrade to a validator node](./validators/validator-setup.md) - -## Join the Cosmos Hub Public Testnet - -- [Join the testnet](./hub-tutorials/join-testnet.md) - -## Setup Your Own `gaia` Testnet - -- [Setup your own `gaia` testnet](https://github.com/cosmos/testnets/tree/master/local/previous-local-testnets/v7-theta) - -## Additional Resources - -- [Validator Resources](./validators/README.md): Contains documentation for `gaia` validators. -- [Delegator Resources](./delegators/README.md): Contains documentation for delegators. -- [Other Resources](./resources/README.md): Contains documentation on `gaiad`, genesis file, service providers, ledger wallets, ... -- [Cosmos Hub Archives](./resources/archives.md): State archives of past iteration of the Cosmos Hub. - -# Contribute - -See [this file](./DOCS_README.md) for details of the build process and -considerations when making changes. diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 1729a5bbaf7..758e26de183 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -7,10 +7,10 @@ import { currentParams } from '@site/docs/governance/current-parameters.js'; import { PlainVar } from '@site/src/js/Var'; :::tip -### **v15.1 Upgrade** -Cosmos Hub will be upgraded to [v15.1](https://github.com/cosmos/gaia/releases/tag/v15.1.0) at block height: **[19,639,600](https://www.mintscan.io/cosmos/blocks/19639600)** +### **v16 Upgrade** +Cosmos Hub will be upgraded to [v16](https://github.com/cosmos/gaia/releases/tag/v16.0.0) at block height: **[20,440,500](https://www.mintscan.io/cosmos/blocks/20440500)** -To upgrade from v14 check the [**upgrade guide**](/migration/cosmoshub-4-v15-upgrade.md) +To upgrade from v15.2.0 check the [**upgrade guide**](./migration/latest.md) ::: ![Welcome to the Cosmos Hub](images/cosmos-hub-image.jpg) diff --git a/docs/docs/interchain-security/README.md b/docs/docs/interchain-security/README.md index 2e1c5f68b60..b61408f1eb7 100644 --- a/docs/docs/interchain-security/README.md +++ b/docs/docs/interchain-security/README.md @@ -1,8 +1,6 @@ --- title: Interchain Security -order: false -parent: - order: 2 +order: 3 --- The Interchain Security feature, brings to the Cosmos Hub a shared security model, where the Cosmos Hub validators, also validate on consumer chains. This is valuable for consumer chains, as consumer chains can focus on product-market fit, rather than business and operational agreements in bringing together a validator set. As part of this agreement, consumer chains pay for the security by distributing a portion of the consumer chain revenue to Hub token holders. diff --git a/docs/docs/metaprotocols/_category_.json b/docs/docs/metaprotocols/_category_.json deleted file mode 100644 index 1a5075eb193..00000000000 --- a/docs/docs/metaprotocols/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Metaprotocol support", - "position": 15, - "link": { "type": "doc", "id": "metaprotocols/README" } -} \ No newline at end of file diff --git a/docs/docs/migration/README.md b/docs/docs/migration/README.md index 2468a3bbeea..c307a2813ea 100644 --- a/docs/docs/migration/README.md +++ b/docs/docs/migration/README.md @@ -1,17 +1,15 @@ --- order: false parent: - title: Migration Instructions - order: 9 + title: Upgrade Instructions --- - -# Migration Instructions -This directory houses Cosmos Hub major upgrade migration instructions. +# Upgrading -- [Upgrading from `cosmoshub-2` to `cosmoshub-3`](./cosmoshub-2/cosmoshub-2.md) -- [Upgrading from `cosmoshub-3` to `cosmoshub-4`](./cosmoshub-3/cosmoshub-3.md) - +To upgrade to the latest `cosmoshub-4` version check: +- [latest upgrade](./latest.md) + +To check archived migrations and historic `cosmoshub` versions check: +- [Upgrading from `cosmoshub-2` to `cosmoshub-3`](./archive/cosmoshub-2/cosmoshub-2.md) +- [Upgrading from `cosmoshub-3` to `cosmoshub-4`](./archive/cosmoshub-3/cosmoshub-3.md) diff --git a/docs/docs/migration/_category_.json b/docs/docs/migration/_category_.json index daa38e63886..328b468cbc6 100644 --- a/docs/docs/migration/_category_.json +++ b/docs/docs/migration/_category_.json @@ -1,5 +1,5 @@ { - "label": "Migration Instructions", + "label": "Upgrade Instructions", "position": 9, "link": { "type": "doc", "id": "migration/README" } } \ No newline at end of file diff --git a/docs/docs/migration/archive/README.md b/docs/docs/migration/archive/README.md new file mode 100644 index 00000000000..f895ae0fba2 --- /dev/null +++ b/docs/docs/migration/archive/README.md @@ -0,0 +1,16 @@ +--- +order: false +parent: + title: Archived Instructions +--- + + +# Archive + +This directory houses archived Cosmos Hub major upgrade migration instructions. + +The migrations are not relevant for mainnet, but you may find them useful in case you are providing infrastructure for historic versions of the Cosmos Hub. + +To view archived migrations for old versions check: +- [Upgrading from `cosmoshub-2` to `cosmoshub-3`](./cosmoshub-2/cosmoshub-2.md) +- [Upgrading from `cosmoshub-3` to `cosmoshub-4`](./cosmoshub-3/cosmoshub-3.md) diff --git a/docs/docs/migration/cosmoshub-2/_category_.json b/docs/docs/migration/archive/cosmoshub-2/_category_.json similarity index 100% rename from docs/docs/migration/cosmoshub-2/_category_.json rename to docs/docs/migration/archive/cosmoshub-2/_category_.json diff --git a/docs/docs/migration/cosmoshub-2/cosmoshub-2.md b/docs/docs/migration/archive/cosmoshub-2/cosmoshub-2.md similarity index 100% rename from docs/docs/migration/cosmoshub-2/cosmoshub-2.md rename to docs/docs/migration/archive/cosmoshub-2/cosmoshub-2.md diff --git a/docs/docs/migration/cosmoshub-3/_category_.json b/docs/docs/migration/archive/cosmoshub-3/_category_.json similarity index 100% rename from docs/docs/migration/cosmoshub-3/_category_.json rename to docs/docs/migration/archive/cosmoshub-3/_category_.json diff --git a/docs/docs/migration/cosmoshub-3/cosmoshub-3.md b/docs/docs/migration/archive/cosmoshub-3/cosmoshub-3.md similarity index 100% rename from docs/docs/migration/cosmoshub-3/cosmoshub-3.md rename to docs/docs/migration/archive/cosmoshub-3/cosmoshub-3.md diff --git a/docs/docs/migration/archive/cosmoshub-4/_category_.json b/docs/docs/migration/archive/cosmoshub-4/_category_.json new file mode 100644 index 00000000000..02c391ea2cd --- /dev/null +++ b/docs/docs/migration/archive/cosmoshub-4/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "CosmosHub-4", + "position": 3, + "link": null +} \ No newline at end of file diff --git a/docs/docs/migration/cosmoshub-4-v10-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v10-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v10-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v10-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v11-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v11-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v11-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v11-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v12-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v12-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v12-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v12-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v13-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v13-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v13-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v13-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v14-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md similarity index 99% rename from docs/docs/migration/cosmoshub-4-v14-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md index 0cb9a6df817..92f87021e09 100644 --- a/docs/docs/migration/cosmoshub-4-v14-upgrade.md +++ b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v14-upgrade.md @@ -56,7 +56,7 @@ The chain-id of the network will remain the same, `cosmoshub-4`. This is because ## Preparing for the upgrade -System requirements for validator nodes can be found [here](../getting-started/system-requirements.md). +System requirements for validator nodes can be found [here](../../../getting-started/system-requirements.md). ### Backups diff --git a/docs/docs/migration/cosmoshub-4-v15-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md similarity index 99% rename from docs/docs/migration/cosmoshub-4-v15-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md index 151499c6298..f6f9894a1e6 100644 --- a/docs/docs/migration/cosmoshub-4-v15-upgrade.md +++ b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v15-upgrade.md @@ -73,7 +73,7 @@ Optimal CPU performance:  2.50GHz, 8 cores (eg Intel Xeon Gold 6248 or equivale It is paramount that the operators set enough SWAP to cover all cases. SWAP partitions can be used to supplement the RAM requirement but they will increase the upgrade time. -After the upgrade you can revert your hardware setting to the recommended system requirements for normal [day-to-day operations](../getting-started/system-requirements.md). +After the upgrade you can revert your hardware setting to the recommended system requirements for normal [day-to-day operations](../../../getting-started/system-requirements.md). ### Backups diff --git a/docs/docs/migration/cosmoshub-4-v5-delta-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v5-delta-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v5-delta-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v5-delta-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v6-vega-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v6-vega-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v6-vega-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v6-vega-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v7-Theta-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v7-Theta-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v7-Theta-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v7-Theta-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v8-Rho-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v8-Rho-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v8-Rho-upgrade.md diff --git a/docs/docs/migration/cosmoshub-4-v9-Lambda-upgrade.md b/docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v9-Lambda-upgrade.md similarity index 100% rename from docs/docs/migration/cosmoshub-4-v9-Lambda-upgrade.md rename to docs/docs/migration/archive/cosmoshub-4/cosmoshub-4-v9-Lambda-upgrade.md diff --git a/docs/docs/migration/latest.md b/docs/docs/migration/latest.md new file mode 100644 index 00000000000..72c63a952f4 --- /dev/null +++ b/docs/docs/migration/latest.md @@ -0,0 +1,200 @@ +--- +title: v16.0.0 Upgrade +--- + +# Upgrading Gaia + +This guide provides instructions for upgrading Gaia from v15.2.x to v16.0.0. + +This document describes the steps for validators, full node operators and relayer operators, to upgrade successfully for the Gaia v16 release. + +For more details on the release, please see the [release notes](https://github.com/cosmos/gaia/releases/tag/v16.0.0) + +**Relayer Operators** for the Cosmos Hub and consumer chains, will also need to update to use [Hermes v1.8.0](https://github.com/informalsystems/hermes/releases/tag/v1.8.0) or higher. You may need to restart your relayer software after a major chain upgrade. + +## Release Binary + +Please use the correct release binary: `v16.0.0`. + +## Instructions + +- [Upgrading Gaia](#upgrading-gaia) + - [Release Binary](#release-binary) + - [Instructions](#instructions) + - [On-chain governance proposal attains consensus](#on-chain-governance-proposal-attains-consensus) + - [Upgrade date](#upgrade-date) + - [Preparing for the upgrade](#preparing-for-the-upgrade) + - [System requirements](#system-requirements) + - [An Important Note for Node Operators](#an-important-note-for-node-operators) + - [Backups](#backups) + - [Testing](#testing) + - [Current runtime](#current-runtime) + - [Target runtime](#target-runtime) + - [Upgrade steps](#upgrade-steps) + - [Method I: Manual Upgrade](#method-i-manual-upgrade) + - [Method II: Upgrade using Cosmovisor](#method-ii-upgrade-using-cosmovisor) + - [Manually preparing the binary](#manually-preparing-the-binary) + - [Preparation](#preparation) + - [Expected upgrade result](#expected-upgrade-result) + - [Auto-Downloading the Gaia binary](#auto-downloading-the-gaia-binary) + - [Upgrade duration](#upgrade-duration) + - [Rollback plan](#rollback-plan) + - [Communications](#communications) + - [Risks](#risks) + - [Reference](#reference) + +## On-chain governance proposal attains consensus + +Once a software upgrade governance proposal is submitted to the Cosmos Hub, both a reference to this proposal and an `UPGRADE_HEIGHT` are added to the [release notes](https://github.com/cosmos/gaia/releases/tag/v16.0.0). +If and when this proposal reaches consensus, the upgrade height will be used to halt the "old" chain binaries. You can check the proposal on one of the block explorers or using the `gaiad` CLI tool. + +## Upgrade date + +The date/time of the upgrade is subject to change as blocks are not generated at a constant interval. You can stay up-to-date by checking the estimated estimated time until the block is produced one of the block explorers (e.g. https://www.mintscan.io/cosmos/blocks/`UPGRADE_HEIGHT`). + +## Preparing for the upgrade + +### Backups + +Prior to the upgrade, validators are encouraged to take a full data snapshot. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the `.gaia` directory. +If you use Cosmovisor to upgrade, by default, Cosmovisor will backup your data upon upgrade. See below [upgrade using cosmovisor](#method-ii-upgrade-using-cosmovisor) section. + +It is critically important for validator operators to back-up the `.gaia/data/priv_validator_state.json` file after stopping the gaiad process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. + +### Testing + +For those validator and full node operators that are interested in ensuring preparedness for the impending upgrade, you can run a [v16 Local Testnet](https://github.com/cosmos/testnets/tree/master/local) or join in our [Cosmos Hub Public Testnet](https://github.com/cosmos/testnets/tree/master/public). + +### Current runtime + +The Cosmos Hub mainnet network, `cosmoshub-4`, is currently running [Gaia v15.2.0](https://github.com/cosmos/gaia/releases/v15.2.0). We anticipate that operators who are running on v15.2.0, will be able to upgrade successfully. Validators are expected to ensure that their systems are up to date and capable of performing the upgrade. This includes running the correct binary and if building from source, building with the appropriate `go` version. + +### Target runtime + +The Cosmos Hub mainnet network, `cosmoshub-4`, will run **[Gaia v16.0.0](https://github.com/cosmos/gaia/releases/tag/v16.0.0)**. Operators _**MUST**_ use this version post-upgrade to remain connected to the network. The new version requires `go v1.21` to build successfully. + +## Upgrade steps + +There are 2 ways to upgrade a node: + +- Manual upgrade +- Upgrade using [Cosmovisor](https://pkg.go.dev/cosmossdk.io/tools/cosmovisor) + - Either by manually preparing the new binary + - Or by using the auto-download functionality (this is not yet recommended) + +If you prefer to use Cosmovisor to upgrade, some preparation work is needed before upgrade. + +### Method I: Manual Upgrade + +Make sure **Gaia v15.2.0** is installed by either downloading a [compatible binary](https://github.com/cosmos/gaia/releases/tag/v15.2.0), or building from source. Check the required version to build this binary in the `Makefile`. + +Run Gaia v15.2.0 till upgrade height, the node will panic: + +```shell +ERR UPGRADE "v16" NEEDED at height: : upgrade to v16 and applying upgrade "v16" at height: +``` + +Stop the node, and switch the binary to **Gaia v16.0.0** and re-start by `gaiad start`. + +It may take several minutes to a few hours until validators with a total sum voting power > 2/3 to complete their node upgrades. After that, the chain can continue to produce blocks. + +### Method II: Upgrade using Cosmovisor + +#### Manually preparing the binary + +##### Preparation + +- Install the latest version of Cosmovisor (`1.5.0`): + +```shell +go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +cosmovisor version +# cosmovisor version: v1.5.0 +``` + +- Create a `cosmovisor` folder inside `$GAIA_HOME` and move Gaia `v15.2.0` into `$GAIA_HOME/cosmovisor/genesis/bin`: + +```shell +mkdir -p $GAIA_HOME/cosmovisor/genesis/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/genesis/bin +``` + +- Build Gaia `v16.0.0`, and move gaiad `v16.0.0` to `$GAIA_HOME/cosmovisor/upgrades/v16/bin` + +```shell +mkdir -p $GAIA_HOME/cosmovisor/upgrades/v16/bin +cp $(which gaiad) $GAIA_HOME/cosmovisor/upgrades/v16/bin +``` + +At this moment, you should have the following structure: + +```shell +. +├── current -> genesis or upgrades/ +├── genesis +│ └── bin +│ └── gaiad # old: v15.2.0 +└── upgrades + └── v16 + └── bin + └── gaiad # new: v16.0.0 +``` + +- Export the environmental variables: + +```shell +export DAEMON_NAME=gaiad +# please change to your own gaia home dir +# please note `DAEMON_HOME` has to be absolute path +export DAEMON_HOME=$GAIA_HOME +export DAEMON_RESTART_AFTER_UPGRADE=true +``` + +- Start the node: + +```shell +cosmovisor run start --x-crisis-skip-assert-invariants --home $DAEMON_HOME +``` + +Skipping the invariant checks is strongly encouraged since it decreases the upgrade time significantly and since there are some other improvements coming to the crisis module in the next release of the Cosmos SDK. + +##### Expected upgrade result + +When the upgrade block height is reached, Gaia will panic and stop: + +This may take a few minutes. +After upgrade, the chain will continue to produce blocks when validators with a total sum voting power > 2/3 complete their node upgrades. + +#### Auto-Downloading the Gaia binary + +## Upgrade duration + +The upgrade may take a few minutes to complete because cosmoshub-4 participants operate globally with differing operating hours and it may take some time for operators to upgrade their binaries and connect to the network. + +## Rollback plan + +During the network upgrade, core Cosmos teams will be keeping an ever vigilant eye and communicating with operators on the status of their upgrades. During this time, the core teams will listen to operator needs to determine if the upgrade is experiencing unintended challenges. In the event of unexpected challenges, the core teams, after conferring with operators and attaining social consensus, may choose to declare that the upgrade will be skipped. + +Steps to skip this upgrade proposal are simply to resume the cosmoshub-4 network with the (downgraded) v15.2.0 binary using the following command: + +```shell +gaiad start --unsafe-skip-upgrade +``` + +Note: There is no particular need to restore a state snapshot prior to the upgrade height, unless specifically directed by core Cosmos teams. + +Important: A social consensus decision to skip the upgrade will be based solely on technical merits, thereby respecting and maintaining the decentralized governance process of the upgrade proposal's successful YES vote. + +## Communications + +Operators are encouraged to join the `#cosmos-hub-validators-verified` channel of the Cosmos Hub Community Discord. This channel is the primary communication tool for operators to ask questions, report upgrade status, report technical issues, and to build social consensus should the need arise. This channel is restricted to known operators and requires verification beforehand. Requests to join the `#cosmos-hub-validators-verified` channel can be sent to the `#general-support` channel. + +## Risks + +As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing. + +The riskiest thing a validator can do is discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. + +## Reference + +[Join Cosmos Hub Mainnet](https://github.com/cosmos/mainnet) diff --git a/docs/docs/modules/README.md b/docs/docs/modules/README.md index 3354f1d6bab..30a0ffeff05 100644 --- a/docs/docs/modules/README.md +++ b/docs/docs/modules/README.md @@ -8,4 +8,5 @@ links for each one. ## Module List -- [Global Fee](./globalfee.md) introduced in [v8 Rho](../migration/cosmoshub-4-v8-Rho-upgrade.md) +- [Global Fee](./globalfee.md) +- [Metaprotocols](./metaprotocols.md) diff --git a/docs/docs/modules/globalfee.md b/docs/docs/modules/globalfee.md index 6ebf22b4fc1..b4b4875dbaa 100644 --- a/docs/docs/modules/globalfee.md +++ b/docs/docs/modules/globalfee.md @@ -1,6 +1,6 @@ --- -title: Gaia Fee and Fees Checks -order: 2 +title: Globalfee +order: 1 --- ## Fee Parameters diff --git a/docs/docs/metaprotocols/README.md b/docs/docs/modules/metaprotocols.md similarity index 97% rename from docs/docs/metaprotocols/README.md rename to docs/docs/modules/metaprotocols.md index 1b4e241fe33..e5c3ec0d175 100644 --- a/docs/docs/metaprotocols/README.md +++ b/docs/docs/modules/metaprotocols.md @@ -1,8 +1,6 @@ --- -title: Metaprotocol Support -order: false -parent: - order: 2 +title: Metaprotocol +order: 2 --- The `x/metaprotocol` module adds support for encoding and decoding additional fields attached to transactions. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 079551ff314..6d1c252c1ae 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -1,75 +1,76 @@ // @ts-check // Note: type annotations allow type checking and IDEs autocompletion -const lightCodeTheme = require('prism-react-renderer/themes/github'); -const darkCodeTheme = require('prism-react-renderer/themes/dracula'); +const lightCodeTheme = require("prism-react-renderer/themes/github"); +const darkCodeTheme = require("prism-react-renderer/themes/dracula"); -const googleTrackingId = 'G-EB7MEE3TJ1'; -const algoliaAppKey = '9AHLYCX3HA'; -const algoliaAPIKey = '976ab1e596812cf4fbe21a3d4d1c9830'; -const algoliaIndexName = 'cosmos_network'; +const googleTrackingId = "G-EB7MEE3TJ1"; +const algoliaAppKey = "9AHLYCX3HA"; +const algoliaAPIKey = "976ab1e596812cf4fbe21a3d4d1c9830"; +const algoliaIndexName = "cosmos_network"; /** @type {import('@docusaurus/types').Config} */ const config = { - title: 'Cosmos Hub', - tagline: '', - favicon: '/gaia/img/hub.svg', + title: "Cosmos Hub", + tagline: "", + favicon: "/gaia/img/hub.svg", // Set the production url of your site here - url: 'https://hub.cosmos.network', + url: "https://hub.cosmos.network", // Set the // pathname under which your site is served // For GitHub pages deployment, it is often '//' - baseUrl: '/', + baseUrl: "/", // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. - organizationName: 'Cosmos', // Usually your GitHub org/user name. - projectName: 'Gaia', // Usually your repo name. + organizationName: "Cosmos", // Usually your GitHub org/user name. + projectName: "Gaia", // Usually your repo name. - onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'throw', + onBrokenLinks: "throw", + onBrokenMarkdownLinks: "throw", trailingSlash: false, // Even if you don't use internalization, you can use this field to set useful // metadata like html lang. For example, if your site is Chinese, you may want // to replace "en" with "zh-Hans". i18n: { - defaultLocale: 'en', - locales: ['en'], + defaultLocale: "en", + locales: ["en"], }, scripts: [ { - src: 'https://kit.fontawesome.com/401fb1e734.js', - crossorigin: 'anonymous', + src: "https://kit.fontawesome.com/401fb1e734.js", + crossorigin: "anonymous", }, ], presets: [ [ - 'classic', + "classic", /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { - routeBasePath: '/', - sidebarPath: require.resolve('./sidebars.js'), - // lastVersion: lastVersion, + routeBasePath: "/", + sidebarPath: require.resolve("./sidebars.js"), + // lastVersion: "v15.2.0", versions: { current: { - path: '/', - banner: 'unreleased', + path: "/", + label: "main", + banner: "unreleased", }, }, }, sitemap: { - changefreq: 'weekly', + changefreq: "weekly", priority: 0.5, - ignorePatterns: ['/tags/**'], - filename: 'sitemap.xml', - }, + ignorePatterns: ["/tags/**"], + filename: "sitemap.xml", + }, blog: false, theme: { - customCss: require.resolve('./src/css/custom.css'), + customCss: require.resolve("./src/css/custom.css"), }, gtag: { trackingID: googleTrackingId, @@ -83,7 +84,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ // Replace with your project's social card - image: 'img/banner.jpg', + image: "img/banner.jpg", docs: { sidebar: { autoCollapseCategories: true, @@ -91,45 +92,45 @@ const config = { }, }, navbar: { - title: 'Cosmos Hub', + title: "Cosmos Hub", hideOnScroll: false, logo: { - alt: 'Cosmos Hub Logo', - src: 'img/hub.svg', - href: 'https://hub.cosmos.network', - target: '_self', + alt: "Cosmos Hub Logo", + src: "img/hub.svg", + href: "https://hub.cosmos.network", + target: "_self", }, items: [ { - type: 'dropdown', - label: 'Community', - position: 'right', + type: "dropdown", + label: "Community", + position: "right", items: [ { - href: 'https://github.com/cosmos/gaia', + href: "https://github.com/cosmos/gaia", html: ' Github', }, { - href: 'https://reddit.com/r/cosmosnetwork', + href: "https://reddit.com/r/cosmosnetwork", html: ' Reddit', }, { - href: 'https://www.youtube.com/c/CosmosProject', + href: "https://www.youtube.com/c/CosmosProject", html: ' YouTube', }, { - href: 'https://discord.gg/cosmosnetwork', + href: "https://discord.gg/cosmosnetwork", html: ' Discord', }, { - href: 'https://forum.cosmos.network/', + href: "https://forum.cosmos.network/", html: ' Cosmos Forums', }, ], }, { - type: 'docsVersionDropdown', - position: 'left', + type: "docsVersionDropdown", + position: "left", dropdownActiveClassDisabled: true, // versions not yet migrated to docusaurus dropdownItemsAfter: [ @@ -143,12 +144,17 @@ const config = { // label: 'v10', // target: '_self', // }, + { + href: "https://github.com/cosmos/gaia/tree/legacy-docs", + label: "Archive", + target: "_blank", + }, ], }, ], }, footer: { - style: 'dark', + style: "dark", links: [ { items: [ @@ -158,65 +164,65 @@ const config = { ], }, { - title: 'Documentation', + title: "Documentation", items: [ { - label: 'Cosmos SDK', - href: 'https://docs.cosmos.network/', + label: "Cosmos SDK", + href: "https://docs.cosmos.network/", }, { - label: 'CometBFT', - href: 'https://docs.cometbft.com/', + label: "CometBFT", + href: "https://docs.cometbft.com/", }, { - label: 'IBC Specs', - href: 'https://github.com/cosmos/ibc', + label: "IBC Specs", + href: "https://github.com/cosmos/ibc", }, { - label: 'IBC Go', - href: 'https://ibc.cosmos.network/', + label: "IBC Go", + href: "https://ibc.cosmos.network/", }, ], }, { - title: 'Community', + title: "Community", items: [ { - label: 'Blog', - href: 'https://blog.cosmos.network/', + label: "Blog", + href: "https://blog.cosmos.network/", }, { - label: 'Forum', - href: 'https://forum.cosmos.network/', + label: "Forum", + href: "https://forum.cosmos.network/", }, { - label: 'Discord', - href: 'https://discord.gg/cosmosnetwork', + label: "Discord", + href: "https://discord.gg/cosmosnetwork", }, { - label: 'Reddit', - href: 'https://reddit.com/r/cosmosnetwork', + label: "Reddit", + href: "https://reddit.com/r/cosmosnetwork", }, ], }, { - title: 'Social', + title: "Social", items: [ { - label: 'Discord', - href: 'https://discord.gg/cosmosnetwork', + label: "Discord", + href: "https://discord.gg/cosmosnetwork", }, { - label: 'Twitter', - href: 'https://twitter.com/cosmoshub', + label: "Twitter", + href: "https://twitter.com/cosmoshub", }, { - label: 'Youtube', - href: 'https://www.youtube.com/c/CosmosProject', + label: "Youtube", + href: "https://www.youtube.com/c/CosmosProject", }, { - label: 'Telegram', - href: 'https://t.me/cosmosproject', + label: "Telegram", + href: "https://t.me/cosmosproject", }, ], }, @@ -226,7 +232,7 @@ const config = { prism: { theme: lightCodeTheme, darkTheme: darkCodeTheme, - additionalLanguages: ['protobuf', 'go-module'], // https://prismjs.com/#supported-languages + additionalLanguages: ["protobuf", "go-module"], // https://prismjs.com/#supported-languages }, algolia: { appId: algoliaAppKey, @@ -235,25 +241,25 @@ const config = { contextualSearch: false, }, }), - themes: ['@you54f/theme-github-codeblock'], + themes: ["@you54f/theme-github-codeblock"], plugins: [ async function myPlugin(context, options) { return { - name: 'docusaurus-tailwindcss', + name: "docusaurus-tailwindcss", configurePostCss(postcssOptions) { - postcssOptions.plugins.push(require('postcss-import')); - postcssOptions.plugins.push(require('tailwindcss/nesting')); - postcssOptions.plugins.push(require('tailwindcss')); - postcssOptions.plugins.push(require('autoprefixer')); + postcssOptions.plugins.push(require("postcss-import")); + postcssOptions.plugins.push(require("tailwindcss/nesting")); + postcssOptions.plugins.push(require("tailwindcss")); + postcssOptions.plugins.push(require("autoprefixer")); return postcssOptions; }, }; }, [ - '@docusaurus/plugin-client-redirects', + "@docusaurus/plugin-client-redirects", { - fromExtensions: ['html'], - toExtensions: ['html'], + fromExtensions: ["html"], + toExtensions: ["html"], redirects: [], }, ], diff --git a/docs/versions.json b/docs/versions.json index c44dc44f37c..cd3c389fb81 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,3 +1,5 @@ [ - + "v15.2.0", + "v16.0.0", + "v17.0.0-rc0" ] \ No newline at end of file