3. CIPs for Editors

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 (visible at the repository front page) where they're tabulated in the README file), 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.

What does a CIP editor 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.

The committee of CIP editors is decentralised with no "leader" or working fields officially set: so at this time the responsibilities for performing any of the actions below are set by habit and personal inclination.

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 pull request queue and issue queue. Eventually, every CIP event such as a CIP posting, comment, or review has to be read and often responded to.

All editors are expected to subscribe 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

Bi-weekly meetings

The public CIP process goes in bi-weekly cycles as defined on our Discord server (see links on home page), 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.

Meeting agenda

All editors will add items to the agenda according to our own involvement with each CIP over time.  To encourage participation by authors and community members, including a CIP PR in a meeting agenda should be announced on GitHub with a link to that agenda.

The agenda itself is a document at this root, which some time soon after the previous meeting should be created for the upcoming meeting by any of the CIP editors: https://hackmd.io/@cip-editors

The agenda "slug" should be the meeting number (e.g. /95 for meeting # 95, with URL https://hackmd.io/@cip-editors/95).  The document & title in the heading should be consistent, and it should follow this template (generally by copying from the previous meeting & editing):

• Triage: add any newly submitted CIP PRs here for an introduction (no detailed review) at the meeting.
• Review: add any CIP PR which has seen lively review, especially those with multiple points of view presented, or is deemed ready to progress based on GitHub commentary.
• Last Check: often following the Last Check label applied in the meantime, include any CIP PR which is deemed ready to merge at, or soon after, the meeting.
• Issues (optional): at editor discretion, include any issue which needs the attention of the developer community ASAP.

Around meeting times (preparation through follow-up)

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 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, the workflow around each of our biweekly CIP meetings would go like this:

• Day or two before meeting: 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.
• Meeting itself: A little over 1 hour for the meeting itself.
• Follow-up: 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 since CIP responsibility has been taken on by working groups at Cardano's major development companies. Our only record of progress and consensus has to be the GitHub commentary that editors transcribe or summarise from CIP meetings.

We see the most benefit from the CIP meetings when the most vocal or active editor for each CIP pull request immediately accepts responsibility to document the relevant resolutions made at the meeting, with a summary comment on the GitHub PR thread for that CIP, tagging the author & any concerned parties.

This latter task is especially vital, since it ensures 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.

Note

It has not been feasible to transcribe the meetings since Q3 2022 due to too many voice recognition problems.

Spontaneous activities

The CIP review commentary on GitHub often leads to efforts outside of the stream of GitHub comments. When significant, editors should take these actions, inviting interested community members to participate as necessary:

• 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 CIP Discord 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 (some examples: 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), with possible updates to CIP-0001
• 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, working groups, and SPO / Developer calls

When possible, long-standing issues discussed outside of GitHub (on social channels or working groups) should always be summarised & posted on GitHub whenever they affect active issues or CIP pull requests.

State Tagging

Formalised in mid-2024: an adaptive process considering the evolution of new CIP/CPS PRs and updates to follow a state-machine type process: see heading for more details, state explanations & diagram.

READ ON for goals of the CIP process & means of measuring its success:

• 31. Practical goals
• 32. Subjective & indirect goals
• 33. Assessment of community satisfaction