-
Notifications
You must be signed in to change notification settings - Fork 318
2. CIPs for Reviewers & Authors
CIPs have been periodically proposed on the GitHub repository and/or the Cardano Forum CIPs category which cannot be put into the form required by CIP-0001 in a way that produces a document of potential use across the Cardano community.
The standing suggestion for such technical contributions is to publish them elsewhere: as blog entries, software documentation, web site landing pages, white papers, etc. Here are some criteria authors and reviewers can use to assess a document's suitability as a CIP:
The three main parts of CIP-0001 force authors to think logically about what they are proposing to the community, by breaking it into:
- Motivation: what has gone (in the past) to indicate a solution to a specific problem is desirable;
- Specification: what should be done (in the present) to create a solution to that problem;
- Rationale: how that solution is preferable to other approaches that could be taken now & in the future.
If it cannot be expressed in these terms, it could really be a "wish" for conditions to be different, or a characterisation of a problem rather than a solution. In either case, authors should consider the CPS format or possibly a social posting to gather community & developer opinions about how such a desire for change could be more precisely expressed.
Both CIPs and CPSs must be independent of organisational and human behaviour. The purpose of the CIP Process & repository is to characterise the behaviour of a blockchain and its related tooling rather than what anyone wants other individuals to do.
For examples, tentative CIPs before have included:
- requests for agencies like the Cardano Foundation, IOG and other compnaies to invest their funds or stake their Ada tokens a certain way;
- alternatives or proposed modifications to the keystone Governance CIP (CIP-1694) indicating personal restrictions, legal consequences, and more.
As with all material inappropriate for CIPs, the best means of expressing these proposals for humans & organisations would be blog or social postings.
Both authors and reviewers should first read CIP-0001 in full: including all the "tips", notes, details, and section explanations. Early stalls in the CIP editing & review process most often come from missing these details and/or working from intermediate sources (e.g. copying from an older CIP rather than the current CIP template).
Besides CIP-0001 (plus CIP-9999 for the CPS), time has shown that a good CIP comes from these further characteristics beyond the bare format & functional miniumum:
Cardano needs standards that are extensible especially because the nature of the technical industry, and particularly the volatile cryptocurrency industry, requires standards that outlive individual involvement. Original authors cannot in general anticipate the way the industry or their involvement in it might change.
Therefore every CIP or CPS should be written so that any well-qualified author in that field can produce amendments to the document, including future versions of an accepted standard. Also, documents should be free of subjective language or individual assumptions that might incline authors to recreate a viable standard rather than extending & maintaining it.
Ideally, a posted document submitted as a pull request should be written objectively enough that another author in that field can take over advocacy and editing of that document all the way to finally merging it (this has happened in a few cases so far).
The most vital aspect of extensibility is Versioning: a requirement incorporated into CIP-0001 itself after the first 2 years of the CIP process.
Authors should not hesitate to involve the CIP editors in determining which approach to Versioning will best suit the community of Cardano developers & implementors: since developer relations experience over many other CIPs will help bring other reviewers into the discussion to converge upon a system of versioning that avoids problems at each stage of implementation & improvement.
CIP authors should provide, and CIP reviewers should expect, a Rationale that is written like one side of a debate with an unseen counterpart who might not be convinced the proposal is the "right way" of doing something, or might even have a preferred alternative.
The best CIPs will have a Rationale written in a way that anticipates the questions of potential implementors who might not raise an objection if a CIP presents a standard they are initially unwilling to follow. The more different approaches are included in comparison & contrast with the CIP's method, the more confidence the developer / implementor community will feel about making a CIP part of their own development plans.
The list of possible categories in CIPs only has several choices, with some of these ("registered" or "enlisted") categories reserved for organisational teams having exclusive responsibility for development.
If considering posting to an enlisted category, make sure your CIP satisfies the posted requirements for that category:
-
Plutus: CIP-0035: Changes to Plutus Core -
Ledger: CIP-0084: Cardano Ledger Evolution -
Catalyst: TBD -
Consensus: in progress
If you have a working group which believes it needs a new CIP category and intends to satisfy the suggestions about enlistment in the CIP process to establish responsibility for review and implementation, contact the CIP editors by posting an issue or submitting a CIP PR with the desired category & evidence appropriate for its enlistment.
The same characteristics as above (impersonality, extensibility, generality) can be applied to the slightly different arrangement of CPS headings.
Beyond this, imagine your CPS (or the one you are reviewing) encompassing one or more CIPs that have been posted and perhaps some CIPs which have not been written yet: to see if they could satisfy the Use Cases, Goals, and Open Questions well enough that the CIP(s) and CPS could link to each other.
Content of this page — according to authorship established by each "Page history" and site-wide Changelog — is licensed under CC-BY-4.0. Please create an issue or discussion to submit content suggestions or corrections.
Click Pages ⬆️ to see the Wiki section titles (if they're not already expanded).