301. State tagging

The process & reasons for state tagging were introduced through this discussion as the conclusion of a year-long effort to:

• simplify routine work of CIP editors by generating lists of PRs requiring common types of review & discussion;
• automatically produce public lists of pending CIPs, to avoid manually updated lists maintained through the first 4 years of the CIP process;
• avoid unrestrained growth of the pull request queue from PRs with unobservable "stale" states;
• provide the Cardano community with a better view to observe and audit the CIP process.

Note

We use the term tag for our application of a GitHub label.

How to apply state tags

State: tags are:

• only applied to pull requests that create or update a CIP or CPS, and are not still marked a Draft;
• only applied one at a time... so if an editor applies another state, the original one should be removed;
• always applied... so the initial state Triage should be applied as soon as a CIP/CPS is observed in the queue & initially "cleaned up" (see below under Triage label).

TL;DR: every in-progress, reviewable PR has one & only one state tag.

Stateless tags

These kinds of administrative PRs should also be given tags immediately, but not State: tags... since they are manually reviewed by editors outside of the CIP community review process:

• Biweekly / Housekeeping (e.g. biweekly meeting updates when proposals are merged, or periodic deprecations)
• Database updates to shared tables & schemas in the CIP repository (currently for the databases for {CIP-0010, CIP-0067, CIP-0088}

State tag details

Triage

• At least one editor has looked it over and:
  • added link to proposal, if author hasn't
  • confirmed the content is suitable for a CIP, or:
    • tagged Update if it updates an existing CIP
    • tagged Correction if it's a trivial update
    • tagged Translation if it submits or updates a translation for an existing CIP
  • assigned a GitHub Category tag... unless ambiguous
  • (optional) applied a quick format review (header, headings, initial discussion link)
• Produces a Triage discussion for this PR at the next CIP meeting, according to our current agenda format.

Unconfirmed

• Presented in initial CIP meeting discussion (or GitHub equivalent) but not assigned a CIP number yet.

Confirmed

• Presented in initial CIP meeting discussion (or GitHub equivalent), and either:
  • assigned a CIP number (if a new CIP or CPS)
  • agreed to be acceptable as an update (if tagged Update)
• Not the same meaning as CIP/CPS Candidate (see report query) - since this state must also apply to PRs tagged as a CIP/CPS update.

Last Check

• Produces a Last Check discussion for this PR at the next CIP meeting, according to our current agenda format, in which a PR is merged after final confirmation.

Waiting for Author

• Author is expected to indicate reasons why the proposal is not being progressed or to state that it is ready for review.
  • Even if waiting for an CIP-enlisted organisation like Plutus or Ledger, the state Waiting for Author indicates the author is still expected to either post or request confirmation that confirmation is being made by these teams (which often happens in other repositories' PR or issue queues).
• Upon confirmation of review readiness, an editor should apply its previous tag before the "waiting" state.
• Suggestion: after a substantial work cycle of no further comment by author, tag Likely Abandoned.

Likely Abandoned

• Author is expected to confirm that a pull request is going to be completed, as well as indicate what is needed before continuing with review.
• Suggestion: a substantial work cycle in this state, close the PR.

Likely Deprecated

• Apply this tag after a voluntary statement by author, editor, or subject matter expert that a CIP is infeasible, duplicated, or superseded (otherwise it is Likely Abandoned).
• Closing with this tag should not happen automatically, but rather by consensus, when the deprecated state is confirmed on GitHub and/or a CIP meeting.

State flow diagram

flowchart TB
untagged[/new, untagged PR/]
-->|editors sanitise PR|triage(Triage)
-->|discussed at CIP meeting|confirmTest{"assigned<br>CIP number?"}
-->|no|unconfirmed(Unconfirmed)
-->|"Github review,<br>put on agenda again<br>when satisfactory"|confirmTest
confirmTest-->|yes|confirmed(Confirmed)
-->|"passed peer &<br>editor reviews"|lastcheck("Last Check")
-->|"needs further<br>discussion?"|confirmed
lastcheck-->|"discuss at CIP meeting(s)<br>until passing consensus"|merged[/merged PR/]
confirmed-->|no posted progress|waitAuthor("Waiting for Author")
-->|author commits &<br>responds to reviews|confirmed
waitAuthor-->|"substantial period<br>of no response"|abandoned("Likely Abandoned")
-->|author plans or<br>schedules progress|waitAuthor
abandoned-->|"substantial period<br>of no response"|closed[/closed PR/]
confirmed-->|"claim: superseded,<br>rejected, obsolete"|deprecated("Likely Deprecated")
-->|"meeting/review consensus:<br>justified worthy to pursue"|confirmed
deprecated-->|"substantial period<br>of no response"|closed
deprecated-->|"meeting/review consensus:<br>deprecated"|closed

Loading

Reporting based on state tags

View & click the queries below for these "derived" states that are not represented by tags:

List all CIP & CPS candidates

A list of all open PRs that:

• are not in Draft stage, AND
• have a State: tag of Confirmed or Last Check (all others don't indicate active review), AND
• don't have any of the administrative (housekeeping, DB changes) or update (Update, Correction, Translation) tags.

Note:

• It's impractical to have a State: Candidate tag because CIP/CPS updates, corrections, and translations going through the CIP process should not appear publicly as candidates, but still need to be confirmed: hence we use the State: Confirmed tag for all types and then filter the "updates" out of the candidate list.
• This same Candidate query divided into CIP vs. CPS is posted on the top-level repository README.md.

List all open, non-draft, non-administrative PRs

Should show a coloured State: tag on every PR.

List all open, untagged, non-draft PRs

Should always be empty. If any item appears here, an editor must apply either a State: or "stateless" tag.

Warning

If CIP updates, corrections or translations appear on the Candidate list(s) — above or on the top level README.md — they have been state-tagged without the Update, Correction, or Translation tags being applied.

Caution

The queries above, as well as those on the top level README.md, must be reviewed & usually updated whenever a new State: or "stateless" tag is added, divided, combined, removed, or renamed: even from differences in spelling or punctuation (though case-insensitive).

FAQ

Why not more intermediate states, to indicate exactly what we're waiting for?

• When tagging Waiting for Author, Likely Abandoned, or Likely Deprecated, editors are expected to note their reasons for applying this tag... including a message to the author about what is expected to happen next to avoid the progression towards "Abandonment" and then closure.
• Including the reasons in that adjacent comment, rather than the tag, keeps the vocabulary small: therefore with more practical lists of which CIPs are stalled without fragmentation across many possible reasons.