From 57bf21ca1fc6f4faf972c635bc9d6e810e51041a Mon Sep 17 00:00:00 2001 From: Filip Djokic Date: Wed, 11 Dec 2024 13:43:18 +0100 Subject: [PATCH] Re-organize upgrade-related docs --- SUMMARY.md | 6 +- docs/upgrades/README.md | 14 +++-- docs/upgrades/propose-software-upgrade.md | 56 ------------------- docs/upgrades/upgrade-guides/README.md | 5 ++ .../{ => upgrade-guides}/v0.6-upgrade.md | 0 .../{ => upgrade-guides}/v2.0.2-upgrade.md | 0 docs/upgrades/upgrade.md | 55 ++++++++++++++++++ 7 files changed, 73 insertions(+), 63 deletions(-) create mode 100644 docs/upgrades/upgrade-guides/README.md rename docs/upgrades/{ => upgrade-guides}/v0.6-upgrade.md (100%) rename docs/upgrades/{ => upgrade-guides}/v2.0.2-upgrade.md (100%) create mode 100644 docs/upgrades/upgrade.md diff --git a/SUMMARY.md b/SUMMARY.md index 78a1b58..39772c7 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -23,9 +23,11 @@ * [Move validator to a different machine](docs/validator-guide/move-validator.md) * [Backup and restore node keys with Hashicorp Vault](docs/validator-guide/backup-and-restore.md) * [Network-wide Software Upgrades](docs/upgrades/README.md) - * [Upgrade to v0.6.x](docs/upgrades/v0.6-upgrade.md) + * [Previous Upgrade Guides](docs/upgrades/upgrade-guides/README.md) + * [Upgrade to v0.6.x](docs/upgrades/upgrade-guides/v0.6-upgrade.md) + * [Recommended Ubuntu 24.04 LTS Upgrade](docs/upgrades/upgrade-guides/v2.0.2-upgrade.md) * [Creating a software upgrade proposal](docs/upgrades/propose-software-upgrade.md) - * [Recommended Ubuntu 24.04 LTS Upgrade](docs/upgrades/v2.0.2-upgrade.md) + * [Upgrade Guide](docs/upgrades/upgrade.md) ## 🧑‍💻 Developing on cheqd diff --git a/docs/upgrades/README.md b/docs/upgrades/README.md index 443b7ba..c55f0e0 100644 --- a/docs/upgrades/README.md +++ b/docs/upgrades/README.md @@ -4,14 +4,18 @@ Updates to the ledger code running on cheqd mainnet/testnet is voted in via governance proposals on-chain for "breaking" software changes. -We use [semantic versioning](https://semver.org/) to define our software release versions. The latest software version running on chain is in the **v1.x.x** family. Any new release versions that bump only the minor/fix version digits (the second and the third part of release version numbers) is intended to be **compatible** within the family and **does not require** an on-chain upgrade proposal to be made. - -## Latest on-chain software upgrade +We use [semantic versioning](https://semver.org/) to define our software release versions. The latest software version running on chain is in the **v2.x.x** family. Any new release versions that bump only the minor/fix version digits (the second and the third part of release version numbers) is intended to be **compatible** within the family and **does not require** an on-chain upgrade proposal to be made. ## Creating a new software upgrade proposal Network-wide software upgrades are typically initiated by the core development team behind the cheqd project. The process followed for the network upgrade is defined in our [guide on creating a Software Upgrade proposal](propose-software-upgrade.md) via network governance. -## Legacy software upgrade proposals +Additionally, these software upgrades are discussed off-chain on [our discussion forum](https://commonwealth.im/cheqd/discussions) and on [our Discord server](http://cheqd.link/discord-github). + +## Upgrade + +You can find more details on the actual upgrade process under in our [Upgrade Guide](upgrade.md) + +## Previous software upgrade guides -This section lists **previous** software upgrade proposals which are no longer valid for the active mainnet/testnet. +[This section](upgrade-guides) lists **previous** software upgrade proposals and specific instructions on how to execute them. diff --git a/docs/upgrades/propose-software-upgrade.md b/docs/upgrades/propose-software-upgrade.md index 2a86b2b..9808057 100644 --- a/docs/upgrades/propose-software-upgrade.md +++ b/docs/upgrades/propose-software-upgrade.md @@ -91,59 +91,3 @@ cheqd-noded query gov votes At the end of voting period, after `voting_end_time`, the state of proposal with `` should be changed to `PROPOSAL_STATUS_PASSED`, if there was enough votes Also, deposits should be refunded back to the operators. - -## Upgrade - -After the proposal status is marked as passed, the upgrade plan will become active. You can query the upgrade plan details using the following command: - -```bash -cheqd-noded query upgrade plan --chain-id cheqd-mainnet-1 -``` - -This will return output similar to: - -```bash -height: "1000" -info: "" -name: -``` - -At block height 1000, the `BeginBlocker` will be triggered. At this point, the node will be out of consensus, awaiting the upgrade to the new version. - -The log messages like these should be expected: - -```bash -5:17PM ERR UPGRADE "" NEEDED at height: 1000: -5:17PM ERR UPGRADE "" NEEDED at height: 1000: -panic: UPGRADE "" NEEDED at height: 1000: -``` - -Once the new application version is installed and running and 1/3 of the voting power on the network is restored, the node will resume normal operations. - -### Automatic upgrades with Cosmovisor - -If your node is configured to use **Cosmovisor**, the upgrade action will be performed **automatically** at the specified block height. - -To check if your node is configured to run with Cosmovisor, run the following command: - -```bash -systemctl status cheqd-cosmovisor.service -``` - -If there's a running systemd service, running this sub-process `/usr/bin/cosmovisor run start`, then your node is using Cosmovisor. - -### Manual Upgrades for Standalone Nodes - -For **standalone nodes**, follow the instructions in [our installation guide](../setup-and-configure/README.md). Make sure to choose the release suggested in the software upgrade proposal. - -### Node Built from Source Code - -If you are running a node built from source, you will need to: - -1. Refer to the upgrade proposal details. -2. Check out the **git tag** corresponding to the latest release. This is important in cases code in our **main** branch doesn't match the latest release. -3. Build the updated binary. - -### Docker Users - -Additionally, we're also publishing the docker images in our [GitHub Container Registry](https://github.com/cheqd/cheqd-node/pkgs/container/cheqd-node), so in case you're running cheqd node in Docker, you can always find the latest image there. diff --git a/docs/upgrades/upgrade-guides/README.md b/docs/upgrades/upgrade-guides/README.md new file mode 100644 index 0000000..1ac45ef --- /dev/null +++ b/docs/upgrades/upgrade-guides/README.md @@ -0,0 +1,5 @@ +# Specific Upgrade Guides + +## Context + +This section lists **previous** software upgrade proposals and specific instructions on how to execute them. diff --git a/docs/upgrades/v0.6-upgrade.md b/docs/upgrades/upgrade-guides/v0.6-upgrade.md similarity index 100% rename from docs/upgrades/v0.6-upgrade.md rename to docs/upgrades/upgrade-guides/v0.6-upgrade.md diff --git a/docs/upgrades/v2.0.2-upgrade.md b/docs/upgrades/upgrade-guides/v2.0.2-upgrade.md similarity index 100% rename from docs/upgrades/v2.0.2-upgrade.md rename to docs/upgrades/upgrade-guides/v2.0.2-upgrade.md diff --git a/docs/upgrades/upgrade.md b/docs/upgrades/upgrade.md new file mode 100644 index 0000000..04c1c1a --- /dev/null +++ b/docs/upgrades/upgrade.md @@ -0,0 +1,55 @@ +# Upgrade + +After the proposal status is marked as passed, the upgrade plan will become active. You can query the upgrade plan details using the following command: + +```bash +cheqd-noded query upgrade plan --chain-id cheqd-mainnet-1 +``` + +This will return output similar to: + +```bash +height: "1000" +info: "" +name: +``` + +At block height 1000, the `BeginBlocker` will be triggered. At this point, the node will be out of consensus, awaiting the upgrade to the new version. + +The log messages like these should be expected: + +```bash +5:17PM ERR UPGRADE "" NEEDED at height: 1000: +5:17PM ERR UPGRADE "" NEEDED at height: 1000: +panic: UPGRADE "" NEEDED at height: 1000: +``` + +Once the new application version is installed and running and 1/3 of the voting power on the network is restored, the node will resume normal operations. + +## Automatic upgrades with Cosmovisor + +If your node is configured to use **Cosmovisor**, the upgrade action will be performed **automatically** at the specified block height. + +To check if your node is configured to run with Cosmovisor, run the following command: + +```bash +systemctl status cheqd-cosmovisor.service +``` + +If there's a running systemd service, running this sub-process `/usr/bin/cosmovisor run start`, then your node is using Cosmovisor. + +## Manual Upgrades for Standalone Nodes + +For **standalone nodes**, follow the instructions in [our installation guide](../setup-and-configure/README.md). Make sure to choose the release suggested in the software upgrade proposal. + +## Node Built from Source Code + +If you are running a node built from source, you will need to: + +1. Refer to the upgrade proposal details. +2. Check out the **git tag** corresponding to the latest release. This is important in cases code in our **main** branch doesn't match the latest release. +3. Build the updated binary. + +## Docker Users + +Additionally, we're also publishing the docker images in our [GitHub Container Registry](https://github.com/cheqd/cheqd-node/pkgs/container/cheqd-node), so in case you're running cheqd node in Docker, you can always find the latest image there.