(new) CIP-0001 & CIP-9999: Cardano Problem Statements

[KtorZ]

This is a proposal to change CIP-0001 and rework how the CIP process currently function. This includes the introduction of a new type of document: Cardano Problem Statements (CPS); specified as part of CIP-9999 (read as "CIP minus 1").

View CIP-0001 Markdown

View CIP-9999 Markdown

View updated top level README

[rphair]

Brilliant work all around 🤓

The proper lists (rather than comma-separated as before) of authors & discussions look much better in the header. We should be on the lookout to be sure this different syntax also works when GitHub CIP README.md files are scraped onto cips.cardano.org and the Developer Portal.

I'm letting go of the comments I made before about having a template or example file visible on the front page for new visitors, writers, etc. to land on. The links to each template are still difficult to spot, but people will find them if they know they're there. The structure is also clear enough from the Specification > CIPs > Structure section that finding the CIP template isn't vital.

@KtorZ to facilitate agenda preparation for meetings, and quick review of relevant PRs during the meetings, can we have GitHub PR labels corresponding to these Categories? Preferably with the same prefix so they group together (e.g. Category: Meta instead of just Meta)?

In any case I think we would have to add an RSS (Rewards Sharing Schemes) category to this list. Regardless of how any institution decides to respond to these proposals, after over 2 years of RSS proposals there are now several of them which will repeatedly need to be seen as a group, and for which none of the other listed Categories are applicable.

Also, did you have a process in mind for people with CIPs who decide to convert their CIP into a CPS? For example CIP-0050 could be a good candidate for this (though I would happily leave that decision entirely to the author).

[michaelpj]

Looking good!

[michaelpj]

Given my previous comment about CPSs probably having multiple CIPs that "solve" parts of them, I wonder again about having something like "Addressed-by" instead. And perhaps the CPS could move to "Resolved" when it is completely addressed? Because that could also happen if it ceases to be a problem for some other reason.

[KtorZ]

There already is a Proposed Solutions field in the preamble. Having another Addressed-By field feels redundant since, any Proposed Solutions in an Active would be effectively addressing (even partially) the problem. If you're suggesting to rename Proposed Solutions to Addressed-By, that's an option. I have no strong feeling about naming here.

[michaelpj]

I guess it just seems weird to me to put the CPS in the Solved state if only part of the problem has been addressed. That seems misleading. But then, leaving it in Open when it has been partially solved is perhaps also misleading. So I don't know what to do.

[KtorZ]

Then I need to clarify something because, Solved is only assigned to problems that are fully solved. A problem that is only partially solved remains in Open, but is updated accordingly to show what's left to solve.

As @abailly-iohk also hinted once, it's probably better to have CPS be focused on a single "atomic" problem as much as possible to avoid this type of situation.

[michaelpj]

Well, the text says just:

Problems for which one or more solutions have been found and implemented.

Which certainly has left me confused about the partial solution state.

As @abailly-iohk also hinted once, it's probably better to have CPS be focused on a single "atomic" problem as much as possible to avoid this type of situation.

I don't think I agree with this. I think it's very unlikely that the "problem view" lines up with the "solution view" so neatly. In practice we often need to do many things to fully address a user-visible problem!

[abailly-iohk]

The important part is

as much as possible

Of course, real life is messy and problems do not usually align neatly with solutions, but we should encourage definitions of problems that are actionable and "compact", eg. instead of a CPS trying to "Solve world hunger", write a CPS saying "How to salvage France's hypermarkets food trashed?"
Not sure this is a great example but I guess the idea is there

[michaelpj]

"How to salvage France's hypermarkets food trashed?"

... which is hardly going to have one solution, no? :) I just think it's unrealistic to suppose that every CPS will have one solution. In fact, my bet would be that that's the less common case.

[abailly-iohk]

That a problem stated in a CPS has more than one solution is certainly desirable and that's actually what I was, awkwardly, trying to express.

[abailly-iohk]

The idea I was trying to convey is that a CPS should express a problem that has at least one solution which itself could be expressed as a CIP. We want to rule out problems whose solution required something that would not fit in a single CIP (I think).

[michaelpj]

Do we want to explicitly allow for the possibility of having multiple competing presentations of a problem? I guess we can leave it up to the editors.

[michaelpj]

Pondering this in the case of Plutus builtins in particular, and I was wondering about insisting that CIPs proposing Plutus builtins be required to include test cases, or more generally a test plan. Because often the proposer is the one who actually knows what it's supposed to do, so they should include them here.

That made me wonder whether it's something that we want to include in any CIP: the acceptance criteria SHOULD include test cases that must pass, and the implementation plan SHOULD include a testing plan.

WDYT?

[KtorZ]

I think that this is relatively specific to Plutus, and thus, a good candidate for the kind of information which you'd include in the enlisting CIP as additional bits to the process. While this apply to Plutus, it may not apply to other projects.

[michaelpj]

I guess more generally I'm thinking that Acceptance Criteria usually involve some expectations of behaviour change, and it's not unreasonable to expect the proposer to at least broadly sketch out the expected behaviour changes.

e.g. for reference inputs we could have asked me to provide some transaction submission scenarios that would now work. That then is very helpful for generating test cases.

[crptmppt]

as noted in the comment, changing the authors of a CIP is not appropriate. I kindly requests the original authors be kept and that Michael be added as alternative.

[rphair]

Despite practically every sentence being changed in the last draft, I would still support retaining @crptmppt (and maybe others) as an author in the header because of the practical work that went into establishing and documenting the original process.

I don't see how the current evolution of the CIP process which @KtorZ has documented much more rigorously today could ever have happened except as experimental revisions from the old process: both in practice and in the earlier revisions of the document.

The paragraphs & sections in common between old & new documents may have changed completely in text, but they still serve the same purpose as the original. Having expressed those concepts in the first place is just as much a part of this living document as the current text itself.

[rphair]

I'm still happy to go ahead with this, especially now that #366 (review) has been tentatively resolved by restoring @crptmppt to the author list. I am guessing the red flag might still remain because @SebastienGllmt @dcoutts haven't been similarly restored?

If this is still a potential blocker, I saw on EIP-1 the EIP Editors section has a list of "Emeritus EIP editors" to indicate substantial prior contributions. Maybe @KtorZ that would work for CIP-0001 (e.g. "Emeritus authors") if that's a way to go forward that places everyone where they want to be. This could work for other evolving CIPs as well.

[michaelpj]

Personally, I lean towards the liberal attitude towards authorship: offering credit and thanks is cheap, so the bar for doing it should be low. IMO it costs us nothing to have everyone who ever made a significant contribution to the document listed as an author.

[KtorZ]

Not sure why authorship is so much of a bother here. As I've said, I have no particular wishes to remove authors. The document was simply written from scratch and I "scrapped" the old one, with its authors. The rationale being that I don't want to put words in other people's mouth; and none of the previous CIP-0001 authors have contributed to this new document.

@crptmppt indicated he would like to be preserved in the authors list for the original work on CIP-0001, so I added him back. I will add back @dcoutts and @SebastienGllmt on this new document if they wish to.

[ccgarant]

CIP/CPS part numbering scheme
Since this is a new revision, just something to maybe consider. I haven't seen this done in crypto land, but in engineering land we have easily identifiable drawing and part numbers, like XXX-YYY-ZZZ-AAA format.
E.g. 901-301-001-101

• 901 is the platform
• 301 is a hydraulic part
• 001 is the specific part
• 101 is the revision number (e.g. 103 is the next rev)

Maybe a new, helpful, easy to visually check numbering scheme could be:

• CIP-META-0021B, where B is rev 2
• CPS-WALLET-0003A
• MBO-RSS-0001D

This might cause renumbering/mapping of old CIPs which might be problematic, so maybe:

• CIP-0068-W-1, where W is for Wallet, and 1 is for Rev 1? (or CIP-0068-WALLET-01, MBO-0001-RSS-02, etc.)

Just food for thought and consideration...

[rphair]

@ccgarant that's an interesting suggestion and I would keep considering it in case CIP nomenclature becomes intractable. To assess how much we might need this: the longest running & most used standards numbering scheme of my own engineering career (RFC) has never needed anything more than numbers despite the well defined scopes that it supports.

The fact that information about an RFC always has to be "looked up" by its number alone ironically tends to make the less descriptive title more familiar rather than less: because looking up those references leads, over time, to a familiarity with the initiated. It would disturb many people who work with these standards to call a CIP or RFC document one thing in their head & another in written references.

I'm not trying to debate your idea but I've seen it's overall more concise (in total: between RFC documents and the documents that refer to them) to keep sub-standards within the document itself, deprecate the documents when they go out of date, and maybe split them when they become too complex. The progression of RFC numbers marching on would have been bewildering if they were all loaded with suffixes.

From what I've seen so far, the CIP editors are never going to be able to approve documents exactly as posted & the greatest problems with documents are often the titles. Your scheme would be great if there were unambiguous classifications for every CIP: which is generally not true even with CIPs on straightforward subjects. We'd neither be able to rely on authors to generate properly coded titles nor on readers to find the documents by those codes.

FYI at our last meeting you may recall (already mentioned in #366 (review)) that we can still provide tagging vocabularies on GitHub that contain the classification fields you mention. For revisions it would be inefficient to use anything but GitHub itself which was made explicitly for versioning.

With time these vocabularies & histories can be constructed into a more general web-based search: hopefully something better than what we see on either cips.cardano.org or Ethereum Improvement Proposals today. And until then, this has the advantage of being able to modify the vocabularies & classifications without document titles going out of date.

[abailly-iohk]

I have a meta question about CIPs: I am having a hard time distinguishing the Motivation section from the Rationale section. According to dictionaries:

Motivation: a reason or reasons for acting or behaving in a particular way.
Rationale: a set of reasons or a logical basis for a course of action or belief.

These seems pretty much synonymous to me :thinking_face:

[abailly-iohk]

I am really having a hard time wrapping my head around what Active really means, and how to get there. I wonder if having some form of state machine diagram in the body of the CIP document would not help?

[KtorZ]

@abailly-iohk there used to be a state-machine diagram, but it's basically as simple as:

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Active
    Proposed --> Inactive

Loading

Hence why I don't much see the value in re-adding it to be frank. Maybe it still is a nice visual support? Is there anything I could add to make the definition of what Active means clearer? We've iterated several times on that and I thought that last draft was pretty clear:

An 'Active' CIP has taken effect according to the criteria defined in its 'Path to Active' section.
What that means depends on the nature of the CIP, typically:

• For CIPs that relate to particular projects or pieces of technology, it becomes 'Active' by being implemented and released;
• For changes to the Cardano protocol, a CIP will become 'Active' by being live on the Cardano mainnet;
• For ecosystem standards, it means gaining sufficient and visible adoption in the community.

In the end, each CIP defines what it means to be Active; and the criteria are also up to review to make sure that there's a consensus about them. Now, the status active conveys a notion of completeness; Distinguishing between Proposed and Active is a way to inform potential builders about how ready a particular solution is. Whether it is merely an idea or some kind of established framework.

[abailly-iohk]

Yeah, I agree it's a bit silly... I don't know why but it cannot stick to my mind, perhaps because as you mention it depends on the actual CIP 🤔

[KtorZ]

Perhaps we have focused too much on how to become active but should also explain what are the implications of being 'Active'.

'Active' means completed. It's kind of analogous to a release for a software. The proposal has matured, was challenged and has demonstrated to be solid enough to be followed.

On the CIP process itself, it means that we would generally not substantially change any 'Active' CIP but instead, ask people to make a new one. While still in 'Proposed', it's okay to amend and make changes because it's still an exploratory phase.

[KtorZ]

(sorry, pressed the 'Close with comment' button by accident).

[KtorZ]

@abailly-iohk -> I have slightly reworded the 'Status: Active' section as such:

---

Status: Active

An 'Active' CIP has taken effect according to the criteria defined in its 'Path to Active' section. Said differently, each CIP defines by which criteria it can become 'Active' and those criteria are included in the review process. Exact criteria thereby depends on the nature of the CIP, typically:

• For CIPs that relate to particular projects or pieces of technology, it becomes 'Active' by being implemented and released;
• For changes to the Cardano protocol, a CIP becomes 'Active' by being live on the Cardano mainnet;
• For ecosystem standards, it means gaining sufficient and visible adoption in the community.

A proposal that is 'Active' is considered complete and is synonymous with "production readiness" when it comes to the maturity of a solution. 'Active' CIPs will not be updated substantially (apart from minor edits, proofreading and extra precisions). They can, nevertheless, be challenged through new proposals if need be.

Addressed in #366 (comment)

[rphair]

@abailly-iohk ... distinguishing the Motivation section from the Rationale section...

• Motivation: a reason or reasons for acting or behaving in a particular way.
• Rationale: a set of reasons or a logical basis for a course of action or belief.

These seems pretty much synonymous to me...

They are: but only without respect to the progression of time. In our process, the motivation precedes the evolution of the proposal: so whatever past & current set of conditions that proposal hopes to improve will otherwise remain in force. After we establish that we're doing something about it (as outlined in the proposal), the rationale describes what we'd be doing in the present & future.

Also: in general they do mean the same thing if they are about the same thing. But in the case of CIP's, the "motivation" is for the proposal itself, while the "rationale" is for the method described in the proposal.

[crptmppt]

I changed the authors list to the original authors + added MPJ (for the changes going into 0001). As the CIP process hardly changes beside the CPS addition I feel it is fine to merge with the added change. If there are issues regarding the addended authorship on this PR, I suggest this be submitted as a different CIP #, which can override 0001 (this could then be noted in the body of 0001) - "convenience" should not override facts, having created 0001 and the entire original CIP process, I request original authorship of 0001 be noted in the CIP. 
Other CIP fine as-is.

[rphair]

@KtorZ I've been leaving it to you do "do the honours" and merge this if & when you're ready... but in this case (unlike #331 whose changes were not so fundamental) we've had to link issues, PRs and Cardano Forum threads to section headings in the draft document... which will disappear if the cip-cps-rework branch is deleted.

So please during/after merging keep the branch open for a while: at least until some time in the new year by which time all the migrations should be worked out, with enough time for PRs submitted while these changes have been pending to be reviewed & merged. After a long enough waiting period, the links that break when the branch is finally deleted will be of lesser consequence 😎