CIP-0035 | Update for new CIP-1

[michaelpj]

This updates CIP-35 to be in line with the new CIP-1.

The main changes are:

• Remove some sections that are IMO implied by CIP-1, e.g. the necessity of a clear implementation plan.
• Delete the CIP registry, since you can just list the category
• Explicitly identify the 'Plutus' category and list the reviewers. At the moment it's just me, maybe it should be more people?
• Attempt to clarify the prose a bit.

There's one very questionable thing that I've done, which is to assert that CIPs in the crossover between the Ledger and Plutus should be in both categories. I just went ahead and wrote that here, but I defer to the resolution of #433 and I'll change this depending on what gets decided there.

[rphair]

@michaelpj this is great and also helps for compliance with the new standardisation proceeding via #389. At first view the document structures all look parseable (headers at the right levels) but the new form also needs:

a Path to Active for each one, even ones that are currently Active.

• This is undocumented (or implied) so far because https://github.com/cardano-foundation/CIPs/tree/master/CIP-0001#status-proposed only lists these criteria for Proposed proposals.
• But we are adding this section for all merged CIPs as per Update older CIPs for revised CIP-0001 #389 (comment) and if adding a history of acceptance & implementation retroactively then nobody understands these better than you, so it makes the most sense for you to write it.
• @KtorZ if my understanding after several GitHub exchanges is that we must have Path to Active for every single proposal is incorrect, now would be a good time to correct it (and also to confirm it).

a section at the bottom with a link to the License quoted in the header (editors can edit these in later if missed here).

another nitpick which we might also handle in concierge style: each of the Motivation and Rationale sections now have slightly longer titles:

• Motivation: why is this CIP necessary?
• Rationale: how does this CIP achieve its goals?

... @KtorZ I feel sheepish asking people to add these as the literal section titles, especially considering what it does to the section anchors (instead of simple & immutable anchors like #motivation), but these are mandatory section titles as per https://github.com/cardano-foundation/CIPs/tree/master/CIP-0001#structure.

[rphair]

This CIP preamble needs the same makeover as CIP's 31 to 33 (some obsolete fields here). Note we will also be double checking this in #389.

[rphair]

The duplicate category seems perfectly understandable to me but this syntax still awaits confirmation via issue #433 and probably also (@KtorZ) an update to https://github.com/cardano-foundation/CIPs/tree/master/CIP-0001#categories.

[KtorZ]

There's actually no Ledger category.

[KtorZ]

I mean, it still is not registered. We've added it for some existing CIPs; but I would refrain to add it to any new ones..

[michaelpj]

I'm assuming there will be one, though.

[KtorZ]

I've been assuming for a couple of months too now 🙃

[rphair]

just noting for cross-reference: there is soon going to be one 🙂 #456

[michaelpj]

Thanks, I'll fix those things.

I can add the "Path to Active" although I'm not sure what I'd say. By its nature this CIP is Active in virtue of us endorsing it, so... what?

[rphair]

If sticking to the guidelines as I understand them, maybe something like (edited to your satisfaction):

---

Acceptance Criteria

Agreement upon this CIP by the Plutus team is confirmation of its acceptance.

Implementation Plan

Implementation of the CIP proceeds as a matter of course after the Plutus team agrees upon it.

---

If it sounds dumb to have these tautological paths-to-active then maybe @KtorZ we could allow for its omission in certain cases... 🤔

[rphair]

• Motivation: why is this CIP necessary?
• Rationale: how does this CIP achieve its goals?

@michaelpj since you were also editing CIP-0001 when the longer titles were assigned to these 2 sections maybe you could please also contribute your opinion about the latter part of #439.

[KtorZ]

@michaelpj By its nature this CIP is Active in virtue of us endorsing it

I'd be happy to see just this as a path to active :)

[michaelpj]

I've addressed the comments, and removed the multiple categories. I've attempted to say something sensible about what to do in cases where things fall in the overlap, but we can fix it up later if it proves problematic I guess.

[rphair]

thanks @michaelpj - this all looks both compliant & well explained to me.

@KtorZ are we strictly requiring that the H1 document titles contain the CIP-XXXX identifier as well?

• I ask mainly because they've been edited into CIPs 2 through 4 (and I followed suit with 13) in the course of Update older CIPs for revised CIP-0001 #389.
• It seems to me this could be left up to the author considering the number will be in the published URL and also just above in the header.

Sorry for another nitpick from the format nanny, but also trying to make sure whatever CI we might invent to normalise the presentation doesn't have to be more like an AI. 🤓

[KtorZ]

@KtorZ are we strictly requiring that the H1 document titles contain the CIP-XXXX identifier as well?

Perhaps not. I am on the fence with that. It reads better on Github, but it's currently redundant on the website (see e.g. https://cips.cardano.org/cips/cip1/). Plus, there's the "problem of section heading" that you outlined in #439 ... which makes me think we might just consider dropping it and bumping all section headers to h1 level 🤷

[rphair]

dropping it and bumping all section headers to h1 level

Section headers as H1's is against the SEO point of view in which H1 is synonymous with the page title... while H2's for section headers is perfect. The problem with the current web site rendering is the duplicated H1 title.

So the problem is solved by eliminating the H1 title in the CIP text (allowing the web script to generate the H1 title) but leaving all the section headers as H2 (or making them that way).

@michaelpj any further formatting discussions can go back to #439 and if @KtorZ agrees with the above then your document formatting is fine the way it is... since if there's an extra H1 in the GitHub text then it'll easy to filter out in the web site generator.

[michaelpj]

Okay, sounds like you're happy with this overall then?

[rphair]

Yes 😎