Author: @raulk
Revision: r0, 2019-05-21
Our goal is to design a framework to foster rapid and incremental libp2p specification development, aiming to reduce the barrier to entry for new ideas, increasing the throughput of ideation and crystallisation of breakthrough novel proposals, promoting their evolution and adoption within the ecosystem, while maximising consensus through a common policy for progression across lifecycle stages.
This document defines the policies that regulate specification lifecycle. Our ideas are partially inspired in the W3C Process [0].
We employ two axes to describe the stage of a specification within its lifecycle:
-
Maturity level: classifies the specification in terms of completeness, demonstrability of implementation, community acceptance, and level of technical detail.
We characterize specifications along a three-level, progressive scale:
Level 1: Working DraftLevel 2: Candidate RecommendationLevel 3: Recommendation
-
Status: classifies the operativeness of the specification.
ActiveDeprecatedTerminated
Not all statuses are relevant to all maturity levels. This matrix defines the applicability:
| Active | Deprecated | Terminated | |
|---|---|---|---|
| Working Draft | ✔ | ✔ | |
| Candidate Recommendation | ✔ | ✔ | |
| Recommendation | ✔ | ✔ |
To abbreviate the lifecycle stage of a specification, we combine the maturity level and status into a two-character string:
<abbrv maturity level> ::= "1" | "2" | "3"
<abbrv status> ::= "A" | "D" | "T"
<abbrv lifecycle stage> ::= <abbrv maturity level> <abbrv status>
// example: 1A (Working Draft / Active), 2D (Candidate Recommendation / Deprecated).
We use the following nomenclature in document headers to denote its current lifecycle stage:
<full maturity level> ::= "Working Draft" | "Candidate Recommendation" | "Recommendation"
<full status> ::= "Active" | "Deprecated" | "Terminated"
<lifecycle header> ::= <abbrv lifecycle stage> " – " <full maturity level> " / " <full status>
// example: 1A – Working Draft / Active.
The specification of the system, process, protocol or item is under development.
This level is lightweight and mostly self-directed by the author. We aim to reduce the barrier to entry, and it's designed to allow for iterative experimentation, discovery, and pivoting.
We do not enforce a hard template in an attempt to enhance author's expressability and creativity.
We enter this level by posting an Initial Working Draft that covers:
- context: what is the current situation or a brief overview of the environment the specification targets.
- motivation: why this specification is relevant, and how it advances the status quo.
- scope and rationale: what areas of the technical system the specification impacts.
- goals: what we expect to achieve (positively and negatively) as a result of implementing the specification.
- expected feature set: a summary/enumeration of features the spec provides.
- tentative technical directions: how are we planning to materialise the specification in terms of system design.
Upon submission of an Initial Working Draft, a minimum of three (3) libp2p
contributors are required to express interest and commitment to shepherd and
advise the author(s) throughout the specification process.
The resulting group will constitute the Interest Group, formed by consensus, barring blocking, binding community feedback. We encourage the Interest Group to be heterogeneous yet relevant, and hold representation for libp2p implementation teams across various languages.
The Interest Group will be responsible for expediently awarding the review approvals or feedback necessary to transition the specification across stages.
The Initial Working Draft shall be reviewed by the Interest Group in no
more than 5 working days. Should there be no defects in form, content or
serious technical soundness issues, the Initial Working Draft will be
accepted and merged.
Ideas deemed controversial or breaking, and those that garner subjective opposition, will still be accepted in order to give them a venue to grow, mature and iterate.
Once the Initial Working Draft is merged, the author may continue revising
and evolving their specification by self-approving their own Pull Requests.
To facilitate open progress tracking and observability, as the Working Draft
evolves, the author(s) SHOULD assemble a checklist of items that are pending
specification, explicitly stating which items are compulsory for promoting the
spec to a Candidate Recommendation.
As a Working Draft evolves and shows promise to exit this stage towards a
Candidate Recommendation, the Interest Group shall be expanded by two (2)
additional members, comprising a total of five (5).
We MAY use GitHub's
CODEOWNERS feature
to enforce per-spec approval policies automatically.
A Working Draft can be in either Active or Terminated status.
The changes proposed in the specification are considered plausible and desirable.
The specification document itself is technically complete. It defines wire level formats for interoperability, error codes, algorithms, data structures, heuristics, behaviours, etc., in a way that it is sufficient to enable contributors to develop an interoperable implementation.
There is at least ONE implementation conforming to the specification. That implementation serves as the Reference Implementation.
The promotion from a Working Draft to a Candidate Recommendation is done
via a Pull Request that is reviewed by the Interest Group, allowing 10
working days to elapse to collect feedback from the libp2p community at large.
A Candidate Recommendation can be in either Active or Deprecated status.
There are at least TWO implementations conforming to the specification, with demonstrated cross-interoperability. This is the supreme stage in the lifecycle of a specification.
The promotion from a Candidate Recommendation to a Recommendation is done
via a Pull Request that is reviewed by the Interest Group, allowing 10
working days to elapse to collect feedback from the libp2p community at large.
A Recommendation can be in either Active or Deprecated status.
The specification is actively being worked on (Working Draft), or it is
actively encouraged for adoption by implementers (Candidate Recommendation,
Recommendation).
This is the entry status for all Initial Working Drafts, and is the default
status until some event triggers deprecation or termination.
The specification is no longer applicable and the community actively discourages new implementations from being built, unless requirements for backwards-compatibility are in force.
Transition to this stage is usually triggered when a new version of a related
specification superseding this one reaches the Candidate Recommendation
stage.
The transition from the Active status to the Deprecated status is
performed via a Pull Request that is reviewed by the Interest Group,
allowing 5 working days to elapse to collect feedback from the libp2p
community at large.
A specification in Working Draft maturity level aged without ammassing
consensus in a timely fashion, and it was therefore terminated by the
procedure below.
Procedure for termination: In order to motivate accountability, efficiency and
order, a specification that stays on the Working Draft maturity level for
over 4 months of its initial approval will be transitioned to the Terminated
status automatically.
The author or Interest Group can request extensions up to 2 times (making for a cumulative runway 12 months), and will be granted by consensus if there's evidence of progress and continued author commitment. We consider this an implicit checkpoint to resolve issues that prevent the specification from making progress.
Changes in the membership of an Interest Group are possible at any time.
While we don't maintain a comprehensive enumeration of reasons, common sense applies.
They include events like waning dedication/commitment of members, changes in technical relevance, or violations of the community code of conduct.
[0] W3.org. (2019). World Wide Web Consortium Process Document. [online] Available at: https://www.w3.org/2019/Process-20190301/ [Accessed 21 May 2019].