mirror of
https://github.com/vacp2p/specs.git
synced 2026-01-06 22:13:52 -05:00
libp2p specification framework – lifecycle: maturity level and status (#169)
This commit is contained in:
Raúl Kripalani
233
00-framework-01-spec-lifecycle.md
Normal file
233
00-framework-01-spec-lifecycle.md
Normal file
@@ -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].
|
||||
Reference in New Issue
Block a user