libp2p specification framework – lifecycle: maturity level and status (#169)

00-framework-01-spec-lifecycle.md

@@ -0,0 +1,233 @@
+# libp2p specification framework – lifecycle: maturity level and status
+
+> Author: @raulk
+
+> Revision: r0, 2019-05-21
+
+## Prelude
+
+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].
+
+## Definitions
+
+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 Draft`
+      * `Level 2: Candidate Recommendation`
+      * `Level 3: Recommendation`
+
+  * Status: classifies the operativeness of the specification.
+
+      * `Active`
+      * `Deprecated`
+      * `Terminated`
+
+### Applicability matrix
+
+Not all statuses are relevant to all maturity levels. This matrix defines the
+applicability:
+
+|                               | **Active** | **Deprecated** | **Terminated** |
+| ----------------------------: | :--------: | :------------: | :------------: |
+| **Working Draft**             |     ✔      |                |        ✔       |
+| **Candidate Recommendation**  |     ✔      |        ✔       |                |
+| **Recommendation**            |     ✔      |        ✔       |                |
+
+### Abbreviations
+
+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).
+```
+
+### Document headers
+
+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.
+```
+
+## Maturity levels
+
+### Level 1: Working Draft
+
+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`](https://help.github.com/en/articles/about-code-owners) feature
+to enforce per-spec approval policies automatically.
+
+A `Working Draft` can be in either `Active` or `Terminated` status.
+
+### Level 2: Candidate Recommendation
+
+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.
+
+### Level 3: Recommendation
+
+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.
+
+## Status
+
+### Active
+
+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.
+
+### Deprecated
+
+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.
+
+### Terminated
+
+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.
+
+---
+
+## Interest Group membership changes
+
+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](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+
+## References
+
+[0] W3.org. (2019). World Wide Web Consortium Process Document. [online]
+Available at: https://www.w3.org/2019/Process-20190301/ [Accessed 21 May
+2019].