Adopt the CEP process

[marc-casperlabs]

This is the inaugural CEP for creating more CEPs!

Rendered

Note: I will gradually be adding more reviewers to this and will only merge this once I have a green checkmark from everyone. This should be something we're all on board with!

[osolmaz]

Alternative names were proposed, but rejected in favor of RFC, since it is a well known standard and does not restrict the domain of things discussed. It also does not make us sound self-important.

I see your point. But there could be a risk of collision with Rust and IETF RFCs. We are in a context where colliding with Rust could cause confusion, since Rust is our main language. So unambiguity compels us to sound self-important, I'm afraid.

[marc-casperlabs]

I see your point. But there could be a risk of collision with Rust and IETF RFCs. We are in a context where colliding with Rust could cause confusion, since Rust is our main language. So unambiguity compels us to sound self-important, I'm afraid.

It would be very rare for us to refer to either of these, I think. The Rust project itself is more likely to refer to IETF RFCs than we are, and they are simple to disambiguate ("see CasperLabs RFC1234, Rust RFC 2345, IETF RFC2459"). Typically the "CasperLabs" part would be implied there.

This also becomes less of an issue when linking, since links require the full URL (and thus RFC namespace) to be included.

[osolmaz]

Another question is, whether we'll be using RFCs for decision-making for design and implementation. I know that the summary says:

Make specifications, ideas and implementation guidelines more developer friendly and accessible through the introduction of an easy to use RFCs process.

But I'm concerned that this process will end up serving more than the purpose of just organizing our content. For example, EIPs have additional state that shows whether a proposal has been accepted or rejected by the core devs for implementation.

IETF and Rust are not projects that launch their own cryptocurrencies. For projects like ours, there is a much higher risk of contention due to clashes between various stakeholders.

If our RFCs are to be used in decision-making, we should explicitly state it, and specify the process.

[sacherjj]

Should we have a section for formal definition of who is proposing the change? I know the branch's existence and PR source is an indicator, but would this cover cases where it is more of a group of people suggesting and one doing the leg work?

[marc-casperlabs]

@marc-casperlabs how ecosystem is affected by this proposal. So far we did a lot of our designs on confluence. Like Clarity UX/Ui stuff. Can you tell what categories we include here / what is excluded?

That's up to the team. Right now, the CEP process is mainly written by and for node devs. If we find it useful, other teams are welcome to adopt it it, the first ones looking at this are consensus, economics and governance teams, as far as I can tell.

I am not sure how well it handles UX/Ui stuff that has a lot of graphical assets in it. Maybe watch this for a few days/weeks and then look how things are going?

I'd like to emphasize that this is not a mandatory switch - it started because we needed a better place to put our potentially unpolished tech specs in. We will see in the near future which direction it develops in.

[arcolife]

Agree with Alex. Time to put that voting dapp to good use finally!

re - acceptance of a CEP (by core devs / validators):
2 approvals from core devs seems far too less but like you've already pinned down, maybe another iteration could formalize these guidelines and factor in votes from an on chain dapp for validators/community if need be - carrying PR labels (community-vote, validator-vote, .. )

Although, might as well add a window for last calls.

Definitely needed. Good going 👍

[Fraser999]

Can we copy the contents of "How to create a CEP" into the README once it's merged please? Just makes the repo a little easier to use.

I have a couple of questions:

1. are CEPs expected to be kept up to date with subsequent changes after they're merged? If not (which I expect is the answer) they're not suitable for use as "living documentation". I believe some of the specs we have in Confluence are supposed to be updated as required (but this seems to not really happen). So in theory we might be worse off by following the CEP process.

2. There's no mention of how a CEP should be finished if it's not approved. I take it we'd want something like two core devs to indicate in review comments that it won't get approved, then the PR just gets closed unmerged?

I'll approve this since you're seeking 100% approval before merging, but in all honesty I don't really expect this process will be much better than our current one.

I think there are probably as many drawbacks as there are benefits of using GH comments vs Confluence ones, and I'm a little pessimistic that this process will be so much better for users that it will solve the problem of not having a single process for discussing enhancements (in theory we currently do have such a process - we're just not always following it).

I'm fairly ambivalent about this, and would normally just add comments rather than explicit approval or request for changes. Of course, I'll do my best to follow the process, and I'll be delighted if this does turn out to be significantly better than our current process.

[Fraser999]

Having started in on CEP-0003, I now realise that this is confusing.

The case in point is the sentence "In general, any serialized object is prefixed with a short tag indicating its type, regardless of the chosen serialization format."

I immediately thought "that's wrong", wasted some time writing a comment with examples to point out the error, and then realised further on that you meant that any serialized object should be prefixed by a tag.

Don't you think it'd be more natural to describe the proposed changes as proposed changes rather than changes which have already happened? I'd imagine most CEPs will want to refer to the current state of the code, and that will be difficult to disambiguate from changes suggested in the CEP if we adopt this style.

[marc-casperlabs]

I genuinely don't know, this is copied from the Rust project almost verbatim. It has the nice benefit of stating the actual status quo once it becomes implemented (and then being obsolete again when outdated ;))

How strongly do you feel about this? I can see your points, but they would take a little getting used to. On the other hand, I am assuming the Rust project does it this way for a reason...

[Fraser999]

I don't feel overly strongly, but it's surprising the Rust project specifies it. I glanced at a couple of their RFCs and found them to be talking in terms of "should be", "will be", etc. rather than "is".

Maybe this is just one of those rules which makes so little sense that nobody actually follows it?

Either way, I'm happy to leave this if you prefer and we can always revisit in the future.

[marc-casperlabs]

Maybe this is just one of those rules which makes so little sense that nobody actually follows it?

I certainly won't fault anyone for doing so. It's a bit counterintuitive, for sure.

[zie1ony]

Github-based improvement proposals are great in general. I consider this to be an experiment, which if successful internally could be easily opened to the public. In many (most) aspects GitHub is just a better tool for devs than Confluence and that's the reason to use it.

[marc-casperlabs]

Can we copy the contents of "How to create a CEP" into the README once it's merged please? Just makes the repo a little easier to use.

Might it be crazy to link CEP0001 as the README.md? =)

are CEPs expected to be kept up to date with subsequent changes after they're merged? If not (which I expect is the answer) they're not suitable for use as "living documentation". I believe some of the specs we have in Confluence are supposed to be updated as required (but this seems to not really happen). So in theory we might be worse off by following the CEP process.

I would assume that sometimes they are if minor things are changed, but if the change is due to a new CEP, one would insert a prominent link to the follow-up at least?

The requirements seem to clash a bit here, being able to talk about new ideas and preserving what was discarded vs. having accurate docs for the thing per se. So actual documentation should probably be separate.

There's no mention of how a CEP should be finished if it's not approved. I take it we'd want something like two core devs to indicate in review comments that it won't get approved, then the PR just gets closed unmerged?

We're still figuring that out. I deliberately left that out to not explode the scope here or introduce too much process at once.

I think there are probably as many drawbacks as there are benefits of using GH comments vs Confluence ones, and I'm a little pessimistic that this process will be so much better for users that it will solve the problem of not having a single process for discussing enhancements (in theory we currently do have such a process - we're just not always following it).

If it does not work, you get to tell me "I told you so" as often as you like, that's an upside, right? =)

I'm fairly ambivalent about this, and would normally just add comments rather than explicit approval or request for changes. Of course, I'll do my best to follow the process, and I'll be delighted if this does turn out to be significantly better than our current process.

Thanks. We'll do our best to make it worthwhile.

[Fraser999]

Might it be crazy to link CEP0001 as the README.md? =)

Well... I hesitate to say yes, but yes! Utter madness. :D

It's one more papercut to the process, but more importantly, as the process evolves it'd be great to not have to keep going to different CEPs. If we have to keep updating the link on the README, surely it's as easy to just copy-paste the relevant text?

So actual documentation should probably be separate.

So, let's take the case of the chainspec. Say we'd created a CEP to discuss how that should look and agreed that, you're suggesting we still go ahead and create a technical spec in Confluence as the living document? Significant changes might go through a further CEP and then on agreement, the Confluence doc gets updated and the original CEP gets a link added to the new one. Is that the perceived flow?

(Being pedantic, this is another reason to keep the actual description of the agreed process in the README. That constitutes the documentation resulting from the CEP - the CEP isn't documentation itself)

We're still figuring that out. I deliberately left that out to not explode the scope here or introduce too much process at once.

OK - no probs.

If it does not work, you get to tell me "I told you so" as often as you like, that's an upside, right? =)

I'll try to resist... but I'll be thinking it! :D

[marc-casperlabs]

It's one more papercut to the process, but more importantly, as the process evolves it'd be great to not have to keep going to different CEPs. If we have to keep updating the link on the README, surely it's as easy to just copy-paste the relevant text?

I've made the README.md a link for now, but we should probably only refer to the CEP, while copying the relevant parts from CEP0001 into the README.md. This can be amended once we improve the process, keeping the CEPs as the "historical" reference and the README.md as actual docs.

So, let's take the case of the chainspec. Say we'd created a CEP to discuss how that should look and agreed that, you're suggesting we still go ahead and create a technical spec in Confluence as the living document? Significant changes might go through a further CEP and then on agreement, the Confluence doc gets updated and the original CEP gets a link added to the new one. Is that the perceived flow?

My proposal is that "polished" or live docs live elsewhere. They are the result of the implementation of a CEP. Ideally, this would involve only a copy & paste job. I still vehemently consider this out of scope for this one inaugural CEP, as we will never finish the discussion otherwise ;)

It needn't be Confluence, we have a docs repo already, Rust docs as well. I say we pick up this discussion after this one is merged.

(Being pedantic, this is another reason to keep the actual description of the agreed process in the README. That constitutes the documentation resulting from the CEP - the CEP isn't documentation itself)

That sounds really good to me. I'll update it again as soon as CEP0001 passes.