Repository navigation
docs: make the node upgrade page a clear step-by-step again - #163
Merged
Merged
Conversation
Operators reported the upgrade page became harder to follow after the July rewrite: accurate, but dense reference prose with the per-node-type path buried in a flat list and no clear 'did it work' signal. Restructure into a numbered walkthrough: note current state -> run the installer (network tabs, provisioner/full vs archive) -> start Rusk and confirm, with an explicit success criterion (block height climbing + new blocks in the log). Keeps the accurate caveats (same network/role, installer leaves Rusk stopped, rusk.toml regenerated / archive [http], rollback, testnet resets).
HDauven
marked this pull request as ready for review
November 2, 2026 23:33
Replace the installer-version and log-tail checks on the happy path with ruskquery info/peers/block-height, the same health check used elsewhere in the operator docs. ruskquery version reports the installer release, not the running Rusk binary, so ruskquery info is the correct way to confirm the upgrade. Leave systemctl/journalctl in the failure section, since ruskquery can't answer when the node is down.
Neotamandua
approved these changes
Nov 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Node operators said the Upgrade a node page got harder to follow after the July rewrite (
3322012):The rewrite made the instructions accurate (installer behavior, preserved vs regenerated files, the archive feature-flag gotcha) but turned a friendly linear walkthrough into dense reference prose: the per-node-type path was buried in a flat list of four commands, and the clear "did it work?" payoff from the old page was gone.
What changed
Restructured into a numbered walkthrough without losing any of the accuracy:
Plus a clear "If Rusk doesn't start" section and a condensed "Testnet resets."
Kept from the current page: the "keep the same network and role" caution, the installer-leaves-Rusk-stopped note, the
rusk.tomlregeneration / archive[http]reminder, and the rollback / troubleshooting / manual-resync / fast-sync links.Validation
npm run buildpasses; Starlight reports all internal links valid. Single-file change:operator/guides/upgrade-node.mdx.Draft for review — happy to adjust tone/detail or go further toward fully separate per-node-type sections if that reads better.