From f65572f77dbee36638b1bfd63906b24cb8d61227 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 15:22:38 +0100 Subject: [PATCH 01/10] initial libp2p spec framework maturity process. --- 00-framework-01-maturity.md | 118 ++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 00-framework-01-maturity.md diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md new file mode 100644 index 000000000..e0f91f356 --- /dev/null +++ b/00-framework-01-maturity.md @@ -0,0 +1,118 @@ +# libp2p specification framework – the five-stage maturity process + +> Author: @raulk + +> Revision: r0, 2019-05-21 + +## Prelude + +This document establishes a framework to foster rapid and incremental libp2p +specification development, aiming to reduce the barrier to entry for new +ideas, increasing the throughput of breakthrough creative proposals, promoting +their evolution and adoption within the community, while maximising consensus +around a common lifecycle and criteria for progression across stages. + +We propose a five-stage process to classify the maturity of a specification in +terms of completeness, demonstrability of implementation, community +acceptance, and level of technical detail. It is somewhat inspired in the W3C +Process [0]. + + 1. `Working Draft` + 2. `Candidate Recommendation` + 3. `Recommendation` + 4. `Deprecated` + 5. `Abandoned Draft` + +## Stage 1: Working draft + +The specification of the system, process, protocol or item is under active +development. This stage 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 don't enforce a hard template in an attempt to enhance author +expressability and creativity. + +We enter this stage 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. + +The `Initial Working Draft` shall be reviewed by the community in no more than 3 +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*. + +We MAY use GitHub's +[`CODEOWNERS`](https://help.github.com/en/articles/about-code-owners) feature +to model the approval policy. + +## Stage 2: Candidate Recommendation + +The changes requested by 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 libp2p community in no more than 8 +working days. + +## Stage 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 libp2p community in no more than +8 working days. + +## Stage 4: Deprecated + +The specification is no longer applicable and the community actively +discourages new implementations. + +Transition to this stage is usually the result of a new version of the +specification reaching the `Candidate Recommendation` stage. + +The transition from a `Candidate Recommendation` or a Recommendation stage to +the Deprecated stage is performed via a *Pull Request* that is reviewed by the +libp2p community in no more than 5 working days. + +## Stage 5: Abandoned Draft + +In order to motivate accountability, efficiency and order, a specification +that stays in the `Working Draft` stage for over 4 months of its initial +approval will automatically transition to the `Abandoned Draft` stage. + +Extensions can be requested up to 3 times and will only be granted by +consensus if there's evidence of progress and continued author commitment. + +--- + +## 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]. \ No newline at end of file From 6a4d0b1cadbe18021aed99444bc199d4f99da306 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 15:52:58 +0100 Subject: [PATCH 02/10] fix formatting. --- 00-framework-01-maturity.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index e0f91f356..45a15d46f 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -74,9 +74,9 @@ 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 libp2p community in no more than 8 -working days. +The promotion from a `Working Draft` to a `Candidate Recommendation` is done +via a *Pull Request* that is reviewed by the libp2p community in no more than +8 working days. ## Stage 3: Recommendation @@ -96,9 +96,9 @@ discourages new implementations. Transition to this stage is usually the result of a new version of the specification reaching the `Candidate Recommendation` stage. -The transition from a `Candidate Recommendation` or a Recommendation stage to -the Deprecated stage is performed via a *Pull Request* that is reviewed by the -libp2p community in no more than 5 working days. +The transition from a `Candidate Recommendation` or a `Recommendation` stage +to the `Deprecated` stage is performed via a *Pull Request* that is reviewed +by the libp2p community in no more than 5 working days. ## Stage 5: Abandoned Draft From 66ba7f4a82873c760cb0be3c20a76ee7bede3a4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 17:40:36 +0100 Subject: [PATCH 03/10] model the role of Interest Groups. --- 00-framework-01-maturity.md | 43 ++++++++++++++++++++++++++++++------- 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index 45a15d46f..7738fd6bb 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -46,9 +46,22 @@ We enter this stage by posting an `Initial Working Draft` that covers: * tentative technical directions: how are we planning to materialise the specification in terms of system design. -The `Initial Working Draft` shall be reviewed by the community in no more than 3 -working days. Should there be no defects in form, content or serious technical -soundness issues, the `Initial Working Draft` will be accepted and merged. +Upon submission of an `Initial Working Draft`, a minimum of five (5) 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 3 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, @@ -75,8 +88,9 @@ 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 libp2p community in no more than -8 working days. +via a *Pull Request* that is reviewed by the _Interest Group_, allowing a +minimum of 8 working days to elapse to collect feedback from the libp2p +community at large. ## Stage 3: Recommendation @@ -85,8 +99,9 @@ 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 libp2p community in no more than -8 working days. +via a *Pull Request* that is reviewed by the _Interest Group_, allowing a +minimum of 8 working days to elapse to collect feedback from the libp2p +community at large. ## Stage 4: Deprecated @@ -98,7 +113,8 @@ specification reaching the `Candidate Recommendation` stage. The transition from a `Candidate Recommendation` or a `Recommendation` stage to the `Deprecated` stage is performed via a *Pull Request* that is reviewed -by the libp2p community in no more than 5 working days. +by the _Interest Group_, allowing a minimum of 5 working days to elapse to +collect feedback from the libp2p community at large. ## Stage 5: Abandoned Draft @@ -111,6 +127,17 @@ consensus if there's evidence of progress and continued author commitment. --- +## 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] From 2aae16dfa000dc9eb6d17daf5fc2c23ae1b4e876 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 17:46:06 +0100 Subject: [PATCH 04/10] add checklist recommendation for working drafts. --- 00-framework-01-maturity.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index 7738fd6bb..2dd89ea8a 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -70,9 +70,14 @@ 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`. + We MAY use GitHub's [`CODEOWNERS`](https://help.github.com/en/articles/about-code-owners) feature -to model the approval policy. +to enforce per-spec approval policies automatically. ## Stage 2: Candidate Recommendation From ad14bff31980ea35c9709e42ae8b57099c9739cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 17:53:15 +0100 Subject: [PATCH 05/10] incremental Interest Group headcount as WD matures. --- 00-framework-01-maturity.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index 2dd89ea8a..73956a3c3 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -46,7 +46,7 @@ We enter this stage by posting an `Initial Working Draft` that covers: * 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 five (5) libp2p +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. @@ -75,6 +75,10 @@ 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. From 7b4ad5ad6689b1c7ee3f952fe33c70321287908b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 17:54:02 +0100 Subject: [PATCH 06/10] fix working draft cumulative runway. --- 00-framework-01-maturity.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index 73956a3c3..5bc88e339 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -131,8 +131,9 @@ In order to motivate accountability, efficiency and order, a specification that stays in the `Working Draft` stage for over 4 months of its initial approval will automatically transition to the `Abandoned Draft` stage. -Extensions can be requested up to 3 times and will only be granted by -consensus if there's evidence of progress and continued author commitment. +Extensions can be requested up to 2 times (making for a cumulative runway 12 +months), and will only be granted by consensus if there's evidence of progress +and continued author commitment. --- From 76c0820d6d7443b73a80c5d024b84fd072245fd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Tue, 21 May 2019 17:57:09 +0100 Subject: [PATCH 07/10] bump up deadlines by 2 working days. --- 00-framework-01-maturity.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index 5bc88e339..1f99bdd56 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -59,7 +59,7 @@ 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 3 working days. Should there be no defects in form, content or +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. @@ -98,7 +98,7 @@ 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 a -minimum of 8 working days to elapse to collect feedback from the libp2p +minimum of 10 working days to elapse to collect feedback from the libp2p community at large. ## Stage 3: Recommendation @@ -109,7 +109,7 @@ 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 a -minimum of 8 working days to elapse to collect feedback from the libp2p +minimum of 10 working days to elapse to collect feedback from the libp2p community at large. ## Stage 4: Deprecated From 9b630b90a44b294354dd6a5ee1aa7df79454764f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Wed, 22 May 2019 13:15:18 +0100 Subject: [PATCH 08/10] splinter maturity stages into: maturity level and status. --- 00-framework-01-maturity.md | 156 +++++++++++++++++++++++++----------- 1 file changed, 109 insertions(+), 47 deletions(-) diff --git a/00-framework-01-maturity.md b/00-framework-01-maturity.md index 1f99bdd56..35b5b3d30 100644 --- a/00-framework-01-maturity.md +++ b/00-framework-01-maturity.md @@ -1,4 +1,4 @@ -# libp2p specification framework – the five-stage maturity process +# libp2p specification framework – lifecycle: maturity level and status > Author: @raulk @@ -6,34 +6,72 @@ ## Prelude -This document establishes a framework to foster rapid and incremental libp2p +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 breakthrough creative proposals, promoting -their evolution and adoption within the community, while maximising consensus -around a common lifecycle and criteria for progression across stages. +ideas, increasing the throughput of ideation and crystallization of +breakthrough novel proposals, promoting their evolution and adoption within +the ecosystem, while maximising consensus through a common policy for +progression across lifecycle stages. -We propose a five-stage process to classify the maturity of a specification in -terms of completeness, demonstrability of implementation, community -acceptance, and level of technical detail. It is somewhat inspired in the W3C -Process [0]. +This document defines the policies that regulate specification lifecycle. Our +ideas are partially inspired in the W3C Process [0]. - 1. `Working Draft` - 2. `Candidate Recommendation` - 3. `Recommendation` - 4. `Deprecated` - 5. `Abandoned Draft` +## Definitions -## Stage 1: Working draft +We employ two axes to describe the stage of a specification within its +lifecycle: -The specification of the system, process, protocol or item is under active -development. This stage 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. + * Maturity level: classifies the specification in terms of completeness, + demonstrability of implementation, community acceptance, and level of + technical detail. -We don't enforce a hard template in an attempt to enhance author + 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` + +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 in a two character string: + +``` + ::= "1" | "2" | "3" + ::= "A" | "D" | "T" + ::= +// example: 1A (Working Draft / Active), 2D (Candidate Recommendation / Deprecated). +``` + +## 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 don't enforce a hard template in an attempt to enhance author's expressability and creativity. -We enter this stage by posting an `Initial Working Draft` that covers: +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 @@ -83,9 +121,11 @@ We MAY use GitHub's [`CODEOWNERS`](https://help.github.com/en/articles/about-code-owners) feature to enforce per-spec approval policies automatically. -## Stage 2: Candidate Recommendation +A `Working Draft` can be in either `Active` or `Terminated` status. + +### Level 2: Candidate Recommendation -The changes requested by the specification are considered plausible and +The changes proposed in the specification are considered plausible and desirable. The specification document itself is technically complete. It defines wire @@ -94,46 +134,68 @@ 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. +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 a -minimum of 10 working days to elapse to collect feedback from the libp2p -community at large. +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. -## Stage 3: Recommendation +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 a -minimum of 10 working days to elapse to collect feedback from the libp2p -community at large. +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. -## Stage 4: Deprecated +## 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. +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. -Transition to this stage is usually the result of a new version of the -specification reaching 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. -The transition from a `Candidate Recommendation` or a `Recommendation` stage -to the `Deprecated` stage is performed via a *Pull Request* that is reviewed -by the _Interest Group_, allowing a minimum of 5 working days to elapse to -collect feedback from the libp2p community at large. +### Terminated -## Stage 5: Abandoned Draft +A specification in `Working Draft` maturity level aged without ammassing +consensus in a timely fashion, and it was therefore terminated by the +procedure below. -In order to motivate accountability, efficiency and order, a specification -that stays in the `Working Draft` stage for over 4 months of its initial -approval will automatically transition to the `Abandoned Draft` stage. +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. -Extensions can be requested up to 2 times (making for a cumulative runway 12 -months), and will only be granted by consensus if there's evidence of progress -and continued author commitment. +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. --- @@ -152,4 +214,4 @@ conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). [0] W3.org. (2019). World Wide Web Consortium Process Document. [online] Available at: https://www.w3.org/2019/Process-20190301/ [Accessed 21 May -2019]. \ No newline at end of file +2019]. From 00dd809817f0c4bf2e7d9968e5c7235f820816f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Wed, 22 May 2019 13:24:41 +0100 Subject: [PATCH 09/10] mv 00-framework-01-{maturity,spec-lifecycle}.md --- 00-framework-01-maturity.md => 00-framework-01-spec-lifecycle.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename 00-framework-01-maturity.md => 00-framework-01-spec-lifecycle.md (100%) diff --git a/00-framework-01-maturity.md b/00-framework-01-spec-lifecycle.md similarity index 100% rename from 00-framework-01-maturity.md rename to 00-framework-01-spec-lifecycle.md From b229eb10c7c7a926f81bf5cea2f7394a3295a30d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Kripalani?= Date: Thu, 23 May 2019 10:34:39 +0100 Subject: [PATCH 10/10] tiny edits; specify document header. --- 00-framework-01-spec-lifecycle.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/00-framework-01-spec-lifecycle.md b/00-framework-01-spec-lifecycle.md index 35b5b3d30..83bb51e53 100644 --- a/00-framework-01-spec-lifecycle.md +++ b/00-framework-01-spec-lifecycle.md @@ -8,7 +8,7 @@ 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 crystallization of +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. @@ -37,6 +37,8 @@ lifecycle: * `Deprecated` * `Terminated` +### Applicability matrix + Not all statuses are relevant to all maturity levels. This matrix defines the applicability: @@ -46,16 +48,30 @@ applicability: | **Candidate Recommendation** | ✔ | ✔ | | | **Recommendation** | ✔ | ✔ | | +### Abbreviations + To abbreviate the lifecycle stage of a specification, we combine the maturity -level and status in a two character string: +level and status into a two-character string: ``` - ::= "1" | "2" | "3" - ::= "A" | "D" | "T" - ::= + ::= "1" | "2" | "3" + ::= "A" | "D" | "T" + ::= // 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: + +``` + ::= "Working Draft" | "Candidate Recommendation" | "Recommendation" + ::= "Active" | "Deprecated" | "Terminated" + ::= " – " " / " +// example: 1A – Working Draft / Active. +``` + ## Maturity levels ### Level 1: Working Draft @@ -65,9 +81,9 @@ 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. +experimentation, discovery, and pivoting. -We don't enforce a hard template in an attempt to enhance author's +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: