-
Notifications
You must be signed in to change notification settings - Fork 325
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.
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 underTriage
label).
TL;DR: every in-progress, reviewable PR has one & only one state tag.
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}
- 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
- tagged
- 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.
- Presented in initial CIP meeting discussion (or GitHub equivalent) but not assigned a CIP number yet.
- 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.
- 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.
- 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
orLedger
, the stateWaiting 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).
- Even if waiting for an CIP-enlisted organisation like
- 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
.
- 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.
- 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.
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
View & click the queries below for these "derived" states that are not represented by tags:
A list of all open PRs that:
- are not in Draft stage, AND
- have a
State:
tag ofConfirmed
orLast 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 theState: 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
.
Should show a coloured State:
tag on every PR.
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).
Why not more intermediate states, to indicate exactly what we're waiting for?
- When tagging
Waiting for Author
,Likely Abandoned
, orLikely 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.
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).