Polkadot protocol proposals (RFC process)

I’m not sure if this is the appropriate place to mention this, but it would make sense to me to also move GitHub - w3f/polkadot-spec: The Polkadot Protocol Specification and GitHub - paritytech/json-rpc-interface-spec to the polkadot-fellows organization.

After all, the entire point of RFCs is to modify the spec. An RFC in isolation doesn’t make much sense, it’s just like a pull request while the spec is the source code.

Do we have an owner of this? Otherwise this will never going to happen like other countless issues we already have.

This was already mentioned here:

@joyce is owning this and taking care of it.

Up to this point we always had excluded the RPC api from the Polkadot spec. I can see the advantages of having a RPC api spec, especially to make it easier for people building on Polkadot to use the different node implementations. However, I don’t know if we need to have this “supervized” by the fellowship?

I’m talking about also moving the specs repo in addition to the RFCs repo. This was not mentioned.

And it would still be excluded. They are two different specifications.

Who else is supposed to supervise ecosystem-wide common good specifications? Because Parity isn’t the right actor for this.

Ahh yeah. Sorry! I think this was already somewhere discussed or maybe I just made this up :thinking:

Yeah, I also didn’t said or wanted to say that it should stay with Parity. I was just expressing my own view. I’m not against the proposal, but also not really convinced. If it moves to the fellowship, people in the fellowship will also need to approve these changes which requires knowledge about RPC etc. Not wanting to say that the people that are part of the fellowship don’t have to say anything about these topics, but I’m also not sure that they are the best for this job. Maybe someone else has a stronger opinion on this in either direction.

Designing RPC functions properly requires the technical knowledge of how the core works.
I don’t see anyone more appropriate to have an opinion on RPC functions than the people who design the core protocol.

UI/frontend people should give feedback about what’s wrong with RPC functions, but actually designing/modifying RPC functions without knowing how things work underneath can lead to catastrophies such as the current/“legacy” JSON-RPC API.

I’m generally fine with moving the entire repo to the fellowship and pushing for as much decentralization as possible.

But I have one concern that I would like to share here: maintaining the spec repo (as well as PSPs or PPPs) also requires someone who actively manages PRs, involves other implementers and makes it easily accessible for everyone (see https://spec.polkadot.network/), especially if the plan is to improve the current status and scale all initiatives. Web3 Foundation is/was planning to hire a (potentially 2) “maintainer” for this and trying to create a version that makes it easier for everyone to contribute and is more accessible (see Docusaurus version). Just to mention it here; obviously, such a maintainer or owner of the repos could also be funded via the treasury.

Given that the fellowship members don’t have the mandate/incentive to work on this, and the repos would no longer have a clear owner, the move could lead to even more issues in the future. For example, almost all contributions so far have been from Web3 Foundation (ex-)employees: Contributors to w3f/polkadot-spec · GitHub even though it was always possible for everyone to contribute to it and open issues.

Thanks a lot, by the way, for your contributions @tomaka, and your motivation to improve the current situation, which is clearly far from perfect.

Why would “everyone” contribute?

The specification is not a free-for-all document that anyone can modify. The RFC process are intentionally a gatekeeping process so that modifications to the specification are done in an informed way.

Additionally, I’m also a bit wary of the fact that someone will have to update the specification after an RFC is accepted, because this person could accidentally change the meaning of some details of the text.
I had initially suggested that RFCs should simply be pull requests in the spec repo, and I think that this makes way more sense than having a separate repo because it would force the RFCs to contain the exact text that will end up in the spec.

If you believe that you can detach the form from the content of the specification, and give someone free reign to modify the form only, then I think that you’d be wrong. They are not separable things.

As another side note, I’ve been trying to push the people who wrote Substrate (many of them I know personally) to contribute to the missing corners of the specification, but they just don’t do it.
To me it’s an incredibly important job, more important than fixing bugs, and it’s been frustrating me that nobody cares about this.


In general, I think we both agree here.

By everyone, I mostly meant people familiar with the implementations and have the technical knowledge (wrote Substrate, different implementers… but ideally, also researchers). For them, it should be easy to contribute (nix and adoc aren’t ideal for this at the moment). But others are also welcome to contribute, e.g., create PRs to fix formatting or spelling issues, etc.

I would be fine with RFCs being a pull request directly to the spec repo and, as I said before, also with moving everything to the fellowship.

But in this case, we need a clear owner and process for merging PRs.