Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rephrase networks-and-nodes.md documentation #2153

Closed
wants to merge 6 commits into from
Closed

Rephrase networks-and-nodes.md documentation #2153

wants to merge 6 commits into from

Conversation

Hugo-Trentesaux
Copy link
Contributor

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]

Copy link

netlify bot commented May 14, 2024

Deploy Preview for substrate-docs ready!

Name Link
🔨 Latest commit bd7fb55
🔍 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.

@kianenigma
Copy link
Contributor

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

@Hugo-Trentesaux
Copy link
Contributor Author

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

Copy link
Contributor

@shawntabrizi shawntabrizi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other than the nits, I think your suggested changes are definitely an improvement.

I would say the original author made the common mistake of confusing "blocks" (a bundle of transactions and a block header) with "state at a block" (the actual state of the chain after having applied all state transitions from all previous blocks), and your words add the correct clarity here.

If anything, 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.

Copy link
Contributor Author

@Hugo-Trentesaux Hugo-Trentesaux left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion replace &nbsp; by spaces

content/md/en/docs/learn/networks-and-nodes.md Outdated Show resolved Hide resolved
content/md/en/docs/learn/networks-and-nodes.md Outdated Show resolved Hide resolved
@Hugo-Trentesaux
Copy link
Contributor Author

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 Hugo-Trentesaux closed this by deleting the head repository Jun 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants