substrate-docs icon indicating copy to clipboard operation
substrate-docs copied to clipboard

Rephrase networks-and-nodes.md documentation

Open Hugo-Trentesaux opened this issue 1 year ago • 1 comments

I found this documentation confusing because it mixed --state-pruning and --blocks-pruning concepts and made think that full nodes discard the blocks when they actually discard the states. I come with this rewrite as a suggestion but it may require proofreading by an expert.

As a reminder this is the current node documentation:

     --state-pruning <PRUNING_MODE>
         Specify the state pruning mode.
         
         This mode specifies when the block's state (ie, storage) should be pruned (ie, removed) from the database.
         This setting can only be set on the first creation of the database. Every subsequent run will load the pruning
         mode from the database and will error if the stored mode doesn't match this CLI value. It is fine to drop this
         CLI flag for subsequent runs. Possible values: - archive: Keep the state of all blocks. - 'archive-canonical'
         Keep only the state of finalized blocks. - number Keep the state of the last number of finalized blocks.
         [default: 256]

     --blocks-pruning <PRUNING_MODE>
         Specify the blocks pruning mode.
         
         This mode specifies when the block's body (including justifications) should be pruned (ie, removed) from the
         database. Possible values: - 'archive' Keep all blocks. - 'archive-canonical' Keep only finalized blocks. -
         number Keep the last `number` of finalized blocks.
         
         [default: archive-canonical]

Hugo-Trentesaux avatar May 14 '24 08:05 Hugo-Trentesaux

Deploy Preview for substrate-docs ready!

Name Link
Latest commit bd7fb55fa475a39c2d4ecc97790259b379a9ac54
Latest deploy log https://app.netlify.com/sites/substrate-docs/deploys/66588465d7717100093e83b5
Deploy Preview https://deploy-preview-2153--substrate-docs.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify[bot] avatar May 14 '24 08:05 netlify[bot]

I would recommend updating the corresponding .rs file that generates the --help with the better documentation that you find fit :)

kianenigma avatar May 21 '24 13:05 kianenigma

@kianenigma the --help is fine, I'm just quoting it to justify the changes to the .md files I edited in this PR.

Hugo-Trentesaux avatar May 21 '24 14:05 Hugo-Trentesaux

a small note on this distinction might be helpful somewhere, but is perhaps beyond the scope of this PR, or what the page should be teaching.

I think the difference between "state transition" and "state" is well explained in the "blockchain basics" page (https://docs.substrate.io/learn/blockchain-basics/).

I do not know where the confusion came from, and I feel that emphasizing the difference would induct more confusion.

Hugo-Trentesaux avatar May 24 '24 19:05 Hugo-Trentesaux