Cardano Improvement Proposals (CIPs) — Introduction from an Insider
This 3-part guide is a refinement of our funded proposal for CIP Editing in Cardano’s Project Catalyst Fund 10.
Further articles in the series will be:
Why does Cardano need a CIP process, editors, and development standards?
Ultimately, the success of a blockchain is demonstrated, at least in part, by how broad and useful to developers its documented standards are: as seen already in Bitcoin and Ethereum through their evolution from their initial days of obscurity, through their rise in popularity and value with the addition of modern commercial standards like the Ethereum’s familiar token standard of ERC-20.
Not only do CIPs document what official Cardano blockchain developers are doing to improve core technologies and conventions, they also expand the scope of what the larger Cardano community will deliver: through standards submitted by independent developers and architects. Once a standard is proposed through a CIP, it becomes a reference point upon which other developers and agencies can build: which promotes new applications and broadening markets for Cardano.
Each well defined standard promotes more rapid development since developers have an increasing number of CIP-based tools and methods to employ in their projects. The best example of this so far in Cardano has been the proliferation of NFTs, since they are generally built by third parties according to CIPs coming from the community itself rather than from Cardano’s core developers.
Any developer, engineer, scientist, entrepreneur, or user should have a means of proposing one of these standards. This process is documented in CIP-0001, which defined and created this process… a document which itself is regularly updated as editors and reviewers continue to refine our process in practice.
To see what discussion surrounds these CIPs, see the list of open CIP pull requests (PRs).
What’s a CIP Editor?
CIP Editors (click for current members) are the only GitHub users with permission to merge documents into the CIP repository. This happens after a period in which any concerned party can review the document to find faults and suggest changes. Often the most demanding reviews come from CIP editors and generally all potential flaws in a standard or its documentation are identified and fixed through GitHub comments and biweekly meeting discussions.
Therefore CIP Editors as a group must be familiar with all existing proposed standards documented in the CIP repository (linked at top), while remaining aware of all the pending CIP documents (the pull requests, already linked) and staying in communication with authors, developers and advocates until these documents are refined and “merged” or ultimately deprecated or abandoned.
How is the author involved?
Initially, all members of the CIP Editors group were employees of the official Cardano sponsoring companies (IOG, Emurgo, and the Cardano Foundation). In keeping with open source tradition and to further assure an impartial process, the members have looked for membership outside those companies. I was the first (and so far the only one) of these “community” editors (unaffiliated with any other Cardano enterprise) to be added (in Q3 2021).
The amount of time spent on CIP editing responsibilities varies widely from editor to editor. Current editors employed with the Cardano Foundation and IOG often must focus on CIPs of well defined commercial interest to their respective companies. My own freedom from these attachments currently helps create daily opportunities for all CIP submissions to progress as much as they are able (historically those progressions were mainly made during a bi-weekly review cycle).
For most of the last year I have been funded through Catalyst Fund 9 (Community CIP Editor: 1 year budget — see on Ideascale or Lido Nation) allocating a typical number of hours per week for all CIP Editing tasks: mainly to attend CIP review meetings, review and help authors with proposals, and confirm the viability of the CIP process as its interest to the Cardano community continues to grow.
The result has been an assured baseline of quality and responsiveness to the developer community. Proposal authors must often wait for a deeply technical review — of the kind one of our more highly technical CIP editors can provide — but often there are project team representatives in other Cardano companies or specialised developers who can review a proposal in the meantime. My work in this aspect of “developer relations” has helped assure a good turnaround time for CIPs even though our number of comprehensively qualified reviewers on the editing team itself remains small.
Ever since my arrival into the CIP process based on community advocacy (through the CIP-0013 updates for stake pool links, intended for a better delegation experience) I have also helped build bridges to the CIP process for interested users: not just developers. This includes engagement on the CIP Discord and Matrix channels and the CIP category on the Cardano Forum.
What does a CIP editor actually do?
The goal of all CIP review activities is ultimately for all editors to be aware of the status of open CIP pull requests, while not moving any proposal forward without the appropriate indication of consensus. Everything below has evolved to demonstrate to the entire Cardano community that a quorum of CIP editors are convinced that qualified reviewers in the community cannot find any further technical or writing flaws with a proposed standard.
Daily GitHub review
The CIP process is mostly cyclical, with tasks loosely allocated between CIP Editors: each editor accepting the tasks they feel most qualified to deal with. Routinely editors review the CIP repository PR queue and issue queue. Eventually, every CIP event such as a CIP posting, comment, or review has to be read and often responded to.
For 2 years I have subscribed to all these events from the GitHub CIP repository page through the Watch button in the header: selecting “All Activity”. This generates a variable but continuous stream of email messages across time zones: with a few peak periods primarily in the work week (it’s not possible to measure the number of these events exactly).
Therefore work comes in continuously and is generally not predictable a month or even a day in advance. These items can be observed in any CIP PR or issue thread and most often include the following:
- requests for review from a CIP author
- reviews from a developer or another CIP editor
- comments on reviews from CIP authors or editors (generally all these must be resolved when they request changes to the document, whether or not a change is made)
- general comments from editors, advocates, implementors, or any interested member of the community
- editorial comments that a CIP is ready for promotion or “merging” or that we discuss this at a regular CIP meeting
- merge notifications, when a fully reviewed CIP becomes official: which requires some maintenance on the table in front of the repository.
… or, looked at in terms of the tasks themselves rather than individual GitHub events, including less official view & commentary outside of GitHub:
- “Triaging” new CIP submissions on GitHub (clarifying titles, linking to proposal documents, closing duplicates, tagging initial reviewers)
- Identifying issues needing attention (and attending to them) based on all email coming from CIP GitHub repo in response to all events (comments, reviews, review comments, issues posted, issue comments)
- Reading, and responding to when expected, all CIP related comments on Discord, Matrix and Cardano Forum groups (including Governance topics when touching upon the CIP process)
- Help (for git, GitHub, and CIP process) with improperly submitted CIPs (example)
- Condensing statements of regular progress into a form that can be easily included in monthly community (in my case, Catalyst) reporting
Some of these lead directly or indirectly to efforts outside of the stream of GitHub comments. When significant, other editors or community members will become involved in these, and the work is planned spontaneously (for most of the last year I’ve been documenting these in my monthly Catalyst reports):
- Creating discussions on Cardano Forum (generally the CIPs category) to bring CIP related questions, information, and sometimes new CIP drafts to a larger audience
- Monitoring user-to-user discussion on the Discord or Matrix where particulars of CIPs are discussed, to bring back the most relevant feedback to the GitHub discussion thread
- Rewriting existing CIPs when the need arises (recent example efforts of mine: CIP-72 asset files, CIP-13 protocol definitions)
- Evolutions of the CIP process (e.g. translation / localisation for CIPs, admitting RSS proposals into CIP process)
- Engaging with IOG or Cardano Foundation technical teams and SPO forums regarding highly technical or scientifically inclined proposals, to bring back the results of out-of-band consultation into the documented CIP process
- Any presence required in IOG or Cardano Foundation events such as workshops and SPO / Developer calls
When possible, long-standing issues must always be summarised & posted on GitHub for maximum accountability. Other editors and I will submit these updates when we observe or forecast that a particular problem or issue is becoming important. (We’ll look at some examples in Parts 2 and 3 of this series.)
The public CIP process goes in bi-weekly cycles as defined on our Discord server (invite link), with dates generally posted 1 or 2 meetings in advance. The conversation at this meeting determines the goals that are set for the next 2 weeks: in which actions taken for each CIP related pull request or issue are documented publicly on GitHub.
According to our own involvement with each CIP over time, we will generally declare in advance our presentation of that CIP submission or update in the meeting agenda, which we prepare as a group and suggest items for in parallel: https://hackmd.io/@cip-editors
Preparing for this meeting is often the most time-consuming portion of our bi-weekly schedule, since we must make sure all items on the agenda (often with a spontaneously emerging theme like Plutus or Ledger) have been reviewed and understood as well as possible in advance… so that we can cover all outstanding issues while the relevant developers are all in one conversation for that hour.
For a fully engaged CIP editor (typically for me, and I’ve seen this pattern in other CIP editors as well) the workflow around each of our biweekly CIP meetings would go like this:
- Collect & index all comments on proposals for agenda, to update the proposed agenda, and to connect on GitHub & other channels to help assure presence of relevant parties at meetings.
- A little over 1 hour for the meeting itself.
- Extra time afterward to summarise resolutions for developers, make follow-up comments, and post relevant dialogues to community channels.
The latter item has become particularly important in the last year. Since it has not been feasible to transcribe the meetings since Q3 2022 (too many voice recognition problems), the most vocal or active editor for each issue must accept responsibility to document the resolutions for that issue made at the meeting: typically a summary comment on the GitHub PR thread for that CIP addressed to the author & anyone following the proposal.
This task (GitHub summary of meeting progress) is one role in which I have been outstanding in the last year, helping to ensure that all discussed CIPs remain in engagement between authors, advocates, reviewers, implementors and editors: staying on track each meeting cycle until reaching the goal of merging the CIP.
Monthly reporting & long term projects
While the CIP process above runs in bi-weekly cycles, I also document my own activities in monthly intervals in Catalyst reports, posted here on GitHub (my latest example) so they remain easily accessible to the community. (Presumably CIP editors working for companies like IOG and the Cardano Foundation must also regularly, internally account for their time & activities on the CIP process.)
Some activities can be considered “milestones” requiring more substantial blocks of time. Editors have developed particular CIPs themselves (like the solely authored CIP-0095, community-driven extensions to CIP-0013, the process-defining improvements for CIP-0001, and several more from current editors). Example milestone projects we’ve undertaken in the past are:
- Migration from Crowdcast teleconferencing medium to forum-like community meetings on Discord
- (ongoing) Remediation of old CIP documents to facilitate building into derived web sites
In Part 2 of this series, we’ll cover some of the more substantial projects so far, and then in Part 3 what we’ll be working to accomplish in the year ahead.
Stay tuned for continuation in Part 2: CIPs — Benefits & Goals
To support our work in CIPs and other cryptocurrency standards for security and governance, please delegate to COSD stake pool in your Cardano wallet and follow us on Twitter for related announcements: 🙏