search

w3f / polkadot-spec

The Polkadot Protocol Specification
https://spec.polkadot.network
Creative Commons Attribution Share Alike 4.0 International
180 stars 70 forks source link

Move the parachains-related networking to the right place #651

Open tomaka opened 1 year ago

tomaka commented 1 year ago

Why is https://spec.polkadot.network/chapter-anv#sect-anv-network-messages in a separate section, and not in "Networking"? They are networking protocols.

I know that the organization of the source code makes it look so, but parachains aren't a pluggable extensions to Polkadot. They are core Polkadot mechanisms.

0xCaso commented 1 year ago

Thanks @tomaka!

tomaka commented 1 year ago

It also needs a bit of reorganization. Just moving the sections doesn't really produce a result that makes sense.

bhargavbh commented 1 year ago

Do you mean moving the networking chapter after AnV or reorganisation within the networking chapter? if it's the former, i would say it's fine for Spec to have forward referencing. We would not want to reorg the spec too often as we  received feedback against it. If it's the later, could you elaborate a bit more?

tomaka commented 1 year ago

I mean reorganize the networking chapter. Don't you think it's very confusing? It is very clearly visible that each sub-section was written separately without any coherence by different authors who each had a partial understanding of the networking, and then glued together artificially.

For example the new section 4.8.8 is called "Notification Messages" and 4.8.9 "Request & response", but the whole chapter contains a list of notification and request-responses protocols. The new section 4.8.8 starts with "The notification messages...". Which notification messages? The answer is: the notification messages that are mentioned earlier in the "Availability & Validity" section from which the section was copy-pasted.

bhargavbh commented 1 year ago

Sure, will make another pass to check consistency and coherence.

On Mon, 12 Jun 2023 at 17:39, Pierre Krieger @.***> wrote:

I mean reorganize the networking chapter. Don't you think it's very confusing? It is very clearly visible that each sub-section was written separately without any coherence by different authors who each had a partial understanding of the networking, and then glued together artificially.

For example the new section 4.8.8 is called "Notification Messages" and 4.8.9 "Request & response", but the whole chapter contains a list of notification and request-responses protocols. The new section 4.8.8 starts with "The notification messages...". Which notification messages? The answer is: the notification messages that are mentioned earlier in the "Availability & Validity" section from which the section was copy-pasted. You have to adjust the context a bit.

— Reply to this email directly, view it on GitHub https://github.com/w3f/polkadot-spec/issues/651#issuecomment-1587588388, or unsubscribe https://github.com/notifications/unsubscribe-auth/AJTHCYYMCOUJCTV2RFRTAD3XK4ZZJANCNFSM6AAAAAAY5SW6XA . You are receiving this because you modified the open/close state.Message ID: @.***>

--

Bhargav Bhatt

@.*** Web3 Foundation

-- _Web 3.0 Technologies Foundation is a foundation established under the laws of Switzerland with a registered office at Baarerstrasse 14, 6300 Zug, Switzerland, registered with the trade register of the Canton of Zug under number CHE-322.596.347.

This message and any attachments may contain confidential and/or privileged information. If you have received this email in error, please notify the sender and delete the email immediately. Please also note that we may hold data about you. Please read our privacy policy  https://web3.foundation/privacy-and-cookies/to learn how we handle data and what your rights are. _

0xCaso commented 1 year ago

Moved the changes to the branch https://github.com/w3f/polkadot-spec/tree/issue-651