From a66e7b77d4c3c8ad90022af8bae31094e2bb929b Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 10 Jan 2018 21:14:46 -0800 Subject: first draft template and DEP-0001 --- proposals/0001-dep-process.md | 147 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 proposals/0001-dep-process.md (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md new file mode 100644 index 0000000..25dc80b --- /dev/null +++ b/proposals/0001-dep-process.md @@ -0,0 +1,147 @@ + +Title: **DEP 0001: The Dat Enhancement Proposal Process** + +Short Name: `0001-dep-process` + +Type: Process + +Status: Draft (as of 2018-01-10) + +Github PR: (add HTTPS link here after PR is opened) + + +# Summary +[summary]: #summary + +The DEP ("Request for Comment") process is how the Dat open source community +comes to (distributed) consensus around technical protocol enhancements and +organizational process. + +# Motivation +[motivation]: #motivation + +A public DEP process is expected to increase the quality of core technical +protocols and library implementations (by clarifying changes early in the +process and allowing structured review by more individuals), lower the barrier +to additional implementations of the protocols (by clarifying implementation +details and norms not included in the core specification itself), and to make +the development process more transparent, accessible, and scalable to a growing +group of developers and end users. + +An additional goal of the process is to empower collaborators who are not core +Dat developers or paid staff to participate in community decision making around +protocols and process. Core developers still have special roles and +responsibilities, but need not be a bottleneck or single-point-of-failure for +the ecosystem as a whole. + +# Usage Documentation +[usage-documentation]: #usage-documentation + +The process for proposing and debating a new DEP is: + +* Fork this git repository +* Copy `template.md` to `proposals/0000-my-proposal.md` (don't chose the "next" + number, use zero; `my-proposal` should be a stub identifier for the proposal) +* Fill in the DEP template. The more details you can fill in at the begining, + the more feedback reviewers can leave; on the other hand, the sooner you put + your ideas down in writing, the faster others can point out issues or related + efforts. +* Submit a github pull request for discussion. The proposal will likely be + ammended based on review and comments. The PR will be tagged to indicate + DEP type and status. +* Build consensus. This part of the process is not bounded in time, and will + likely involve both discussion on the PR comment thread and elsewhere (IRC, + etc). +* Consider drafting or prototyping an implementation to demonstrate your + proposal and work out all the details. This step isn't necessary, however: a + proposer does not need to be a developer. +* If consensus seems to have emerged (for or against the proposal), a team + member will assign an DEP number, update the status, and merge the PR. +* Small tweaks (grammar, clarifications) to a merged DEP can take place as + regular github PRs; revisiting or significantly revising should take place as + a new DEP. + +DEPs should have a type ("Standard" or "Process") and a status. + +# Reference Documentation +[reference-documentation]: #reference-documentation + +DEPs should have a type: + +* **Standard** for technical changes to the protocol, on-disk formats, or + public APIs. +* **Process** for formalizing community processes or other (technical or + non-technical) decisions. For example, a security vulnerability reporting + policy, a process for handling conflicts of interest, or procedures for + mentoring new developers. + +The status of an DEP can be: + +* **Draft**: writen up, open PR for discussion +* **Active**: PR accepted; adopted or intended for implementation in mainline + libraries and clients as appropriate +* **Closed**: PR was closed without merging; either consensus was against, a + decision was postponed, or the authors withdrew their proposal. +* **Superseded**: a formerly "active" DEP has been made obsolete by a new + active DEP; the new DEP should specify specific old DEPs that it would + supersede. + +A changelog should be kept in the DEP itself giving the date of any changes of +status. + +A template file is provided, but sections can be added or removed as +appropriate for a specific DEP. + +# Drawbacks +[drawbacks]: #drawbacks + +There are already multiple sources of technical documentation: the Dat +[protocol website][proto-website], the Dat [whitepaper][whitepaper], Dat +website [documentation section][docs], the [discussion repo][discussion-repo] +issues, and the [datprotocol github group][datproto-group] (containing, eg, the +`dat.json` repo/spec). Without consensus and consolidation, this would be "yet +another" place to look. + +[proto-website]: https://www.datprotocol.com/ +[whitepaper]: https://github.com/datproject/docs/blob/master/papers/dat-paper.md +[docs]: https://docs.datproject.org/ +[datproto-group]: https://github.com/datprotocol + +# Rationale and alternatives +[alternatives]: #alternatives + +**TODO:** + +# Unresolved questions +[unresolved]: #unresolved-questions + +Who are "core developers"? What is the specific decision making process for +accepting or rejecting a given DEP? Optimistically, it would be clear from +reading a PR discussion thread whether "consensus" has been reached or not, but +this might be ambiguous or intimidating to first-time contributors. + +When are or are not accepted DEPs binding? Presumably a technical DEP should indicate + +Are "standard"/technical and "process" the right categories and terms to use? +Some DEP systems (like the IETF one) also use terminology like "informational" +(seems like we could rely on blog posts) an "normative". This might be helpful +for documenting things like peer discovery methods, which have intentially not +been specified as part of the formal spec (to make it clear that there is no +single "right way" to do discovery), but they should be documented somewhere. + +Some communities eventually subsume the core protocol specification itself into +the DEP process (for example, the official Bittorrent protocol was documented +in a "BEP"). Should dat do this? Or rely on the current (and possibly future) +Dat whitepaper? + +Is "DEP" the term we want to use? Could also be "Dat Enhancement Proposal" +(DEP), etc. + +# Changelog +[changelog]: #changelog + +A brief statemnt about current status can go here, follow by a list of dates +when the status line of this DEP changed (in most-recent-last order). + +- 2018-01-08: TODO: First complete draft submitted for review + -- cgit v1.2.3 From 201ef339e4b751e60a815bcbaed428906a364c73 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Mon, 15 Jan 2018 23:41:06 -0800 Subject: small typos and clarifications to meta-DEP --- proposals/0001-dep-process.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 25dc80b..438b14f 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -1,11 +1,11 @@ -Title: **DEP 0001: The Dat Enhancement Proposal Process** +Title: **DEP-0001: The Dat Enhancement Proposal Process** Short Name: `0001-dep-process` Type: Process -Status: Draft (as of 2018-01-10) +Status: Draft (as of 2018-01-15) Github PR: (add HTTPS link here after PR is opened) @@ -13,9 +13,9 @@ Github PR: (add HTTPS link here after PR is opened) # Summary [summary]: #summary -The DEP ("Request for Comment") process is how the Dat open source community -comes to (distributed) consensus around technical protocol enhancements and -organizational process. +The DEP ("Dat Enhancement Proposal") process is how the Dat open source +community comes to (distributed) consensus around technical protocol +enhancements and organizational process. # Motivation [motivation]: #motivation @@ -40,21 +40,24 @@ the ecosystem as a whole. The process for proposing and debating a new DEP is: * Fork this git repository -* Copy `template.md` to `proposals/0000-my-proposal.md` (don't chose the "next" - number, use zero; `my-proposal` should be a stub identifier for the proposal) +* Copy `0000-template.md` to `proposals/0000-my-proposal.md` (don't chose the + "next" number, use zero; `my-proposal` should be a stub identifier for the + proposal) * Fill in the DEP template. The more details you can fill in at the begining, the more feedback reviewers can leave; on the other hand, the sooner you put your ideas down in writing, the faster others can point out issues or related - efforts. + efforts. Feel free to tweak or expand the structure (headers, content) of the + document to fit your needs. * Submit a github pull request for discussion. The proposal will likely be - ammended based on review and comments. The PR will be tagged to indicate - DEP type and status. + ammended based on review and comments. Go ahead and `cc:` specific community + members who you think would be good reviewers, though keep in mind + everybody's time and attention is finite.. * Build consensus. This part of the process is not bounded in time, and will likely involve both discussion on the PR comment thread and elsewhere (IRC, etc). * Consider drafting or prototyping an implementation to demonstrate your - proposal and work out all the details. This step isn't necessary, however: a - proposer does not need to be a developer. + proposal and work out all the details. This step isn't strictly necessary, + however: a proposer does not need to be a developer. * If consensus seems to have emerged (for or against the proposal), a team member will assign an DEP number, update the status, and merge the PR. * Small tweaks (grammar, clarifications) to a merged DEP can take place as @@ -120,7 +123,8 @@ accepting or rejecting a given DEP? Optimistically, it would be clear from reading a PR discussion thread whether "consensus" has been reached or not, but this might be ambiguous or intimidating to first-time contributors. -When are or are not accepted DEPs binding? Presumably a technical DEP should indicate +When are or are not accepted DEPs binding? Presumably a technical DEP should +indicate whether it is optional or mandatory. Are "standard"/technical and "process" the right categories and terms to use? Some DEP systems (like the IETF one) also use terminology like "informational" @@ -134,14 +138,11 @@ the DEP process (for example, the official Bittorrent protocol was documented in a "BEP"). Should dat do this? Or rely on the current (and possibly future) Dat whitepaper? -Is "DEP" the term we want to use? Could also be "Dat Enhancement Proposal" -(DEP), etc. - # Changelog [changelog]: #changelog A brief statemnt about current status can go here, follow by a list of dates when the status line of this DEP changed (in most-recent-last order). -- 2018-01-08: TODO: First complete draft submitted for review +- 2018-01-15: TODO: First complete draft submitted for review -- cgit v1.2.3 From 6f86230888a950f9bd63937bbff61ba139a121ae Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Tue, 16 Jan 2018 00:54:16 -0800 Subject: meta-DEP revisions --- 0000-template.md | 4 +- proposals/0001-dep-process.md | 142 ++++++++++++++++++++++++++++-------------- 2 files changed, 98 insertions(+), 48 deletions(-) (limited to 'proposals') diff --git a/0000-template.md b/0000-template.md index 8b746e5..b269b1c 100644 --- a/0000-template.md +++ b/0000-template.md @@ -3,12 +3,14 @@ Title: **DEP-0000: My Proposal** Short Name: `0000-my-proposal` -Type: (Standard or Process) +Type: (Standard, Process, or Informative) Status: Undefined (as of YYYY-MM-DD) Github PR: (add HTTPS link here after PR is opened) +Authors: TBD + # Summary [summary]: #summary diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 438b14f..29838ff 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -7,19 +7,26 @@ Type: Process Status: Draft (as of 2018-01-15) -Github PR: (add HTTPS link here after PR is opened) +Github PR: [https://github.com/datprotocol/DEPs/pull/2]() +Authors: TBD # Summary [summary]: #summary -The DEP ("Dat Enhancement Proposal") process is how the Dat open source +The Dat Enhancement Proposal ("DEP") process is how the Dat open source community comes to (distributed) consensus around technical protocol enhancements and organizational process. # Motivation [motivation]: #motivation +The community around the Dat protocol has grown to the point that standards +documentation and decision making centered around source code (an open +reference implementation) and a single whitepaper is insufficient. A specific +growing pain is the bandwidth of a small number of implementors to respond to +all informal proposals or requests for clarification on their own. + A public DEP process is expected to increase the quality of core technical protocols and library implementations (by clarifying changes early in the process and allowing structured review by more individuals), lower the barrier @@ -30,16 +37,21 @@ group of developers and end users. An additional goal of the process is to empower collaborators who are not core Dat developers or paid staff to participate in community decision making around -protocols and process. Core developers still have special roles and -responsibilities, but need not be a bottleneck or single-point-of-failure for -the ecosystem as a whole. +protocols and process. Certain individuals will have special roles and +responsibilities, but should be less of a bottleneck or single-point-of-failure +for the ecosystem as a whole. + +# Submitting a Proposal +[submit]: #submit -# Usage Documentation -[usage-documentation]: #usage-documentation +Before writing and proposing a DEP, which takes some time, it's best to +informally pitch your idea to see if others are already working on something +very similar, or if your idea has been discussed previously. This could take +place over chat, a short github issue, or any other medium. The process for proposing and debating a new DEP is: -* Fork this git repository +* Fork the [datprotocol/deps](https://github.com/datprotocol/deps) repository * Copy `0000-template.md` to `proposals/0000-my-proposal.md` (don't chose the "next" number, use zero; `my-proposal` should be a stub identifier for the proposal) @@ -48,43 +60,71 @@ The process for proposing and debating a new DEP is: your ideas down in writing, the faster others can point out issues or related efforts. Feel free to tweak or expand the structure (headers, content) of the document to fit your needs. -* Submit a github pull request for discussion. The proposal will likely be - ammended based on review and comments. Go ahead and `cc:` specific community - members who you think would be good reviewers, though keep in mind +* Submit a github pull request for discussion. The initial proposal will likely + be ammended based on review and comments. Go ahead and `cc:` specific + community members who you think would be good reviewers, though keep in mind everybody's time and attention is finite.. -* Build consensus. This part of the process is not bounded in time, and will - likely involve both discussion on the PR comment thread and elsewhere (IRC, - etc). +* Build interest and consensus. This part of the process will likely involve + both discussion on the PR comment thread and elsewhere (IRC, etc). * Consider drafting or prototyping an implementation to demonstrate your proposal and work out all the details. This step isn't strictly necessary, however: a proposer does not need to be a developer. -* If consensus seems to have emerged (for or against the proposal), a team - member will assign an DEP number, update the status, and merge the PR. +* If the DEP is well-formed and there is sufficient interest (for or against + the proposal), a team member will assign an DEP number, update the status, + and merge the PR. Standards DEPs which need implementation or details to be + worked out, can be accepted as "Draft"; DEPs with strong acceptance can go + straight to "Active". +* A "Draft" DEP can be upgraded to "Active" after some time has passed and + confidence has been increased (eg, unresolved issues have been addressed, + implementations have been shown in the wild) by opening a PR for discussion + that sets the new Status. * Small tweaks (grammar, clarifications) to a merged DEP can take place as regular github PRs; revisiting or significantly revising should take place as - a new DEP. + a new DEP. "Draft" and "Process" DEPs have a lower bar for evolution over + time via direct PR. + +All DEPs should have a type ("Standard" or "Process") and a status. + +For appropriate DEPs (including *all* Standards DEPs), authors should +explicitly consider and note impacts on: -DEPs should have a type ("Standard" or "Process") and a status. +* Privacy and User Rights: consider reading IETF [RFC 6973] ("Privacy + Considerations for Internet Protocols") and [RFC 8280] ("Research into Human + Rights Protocol Considerations") +* Backwards compatibility of on-disk archives and older network clients -# Reference Documentation +[RFC-6973]: https://tools.ietf.org/html/rfc6973 +[RFC-8280]: https://tools.ietf.org/html/rfc8280 + +# Details [reference-documentation]: #reference-documentation DEPs should have a type: * **Standard** for technical changes to the protocol, on-disk formats, or - public APIs. + public APIs. These are intented to be *proscriptive*, and to clearly + delineate which features and behaviors are mandatory or optional. * **Process** for formalizing community processes or other (technical or non-technical) decisions. For example, a security vulnerability reporting policy, a process for handling conflicts of interest, or procedures for mentoring new developers. - -The status of an DEP can be: - -* **Draft**: writen up, open PR for discussion -* **Active**: PR accepted; adopted or intended for implementation in mainline - libraries and clients as appropriate -* **Closed**: PR was closed without merging; either consensus was against, a - decision was postponed, or the authors withdrew their proposal. +* **Informative** for describing conventions, design patterns, existing norms, + special considerations, etc. + +The status of a DEP can be: + +* **Pre-Merge**: a well-formed DEP has been written and a PR opened. The + "Status" line can list "Draft" when in this state. +* **Draft**: PR has been merged and a number assigned, but additional time is + needed for deeper discussion or more implementation before being fully + accepted. +* **Active**: adopted or intended for implementation in mainline libraries and + clients as appropriate +* **Closed**: either consensus was against, a decision was postponed, or the + authors withdrew their proposal. This could apply to any of: a proposal PR + that was never merged, a merged Draft (which was never Active), or an Active + DEP which there is now consensus against without a specific new DEP to + replace it. * **Superseded**: a formerly "active" DEP has been made obsolete by a new active DEP; the new DEP should specify specific old DEPs that it would supersede. @@ -95,6 +135,11 @@ status. A template file is provided, but sections can be added or removed as appropriate for a specific DEP. +The DEP text itself should be permissively licensed; the convention is to use +the Creative Commons Attribution License (CC-BY), with attribution to the major +contributing authors listed. + + # Drawbacks [drawbacks]: #drawbacks @@ -110,10 +155,23 @@ another" place to look. [docs]: https://docs.datproject.org/ [datproto-group]: https://github.com/datprotocol -# Rationale and alternatives -[alternatives]: #alternatives +# Background and References +[references]: #references + +The following standards processes were referenced and considered while +designing the DEP process: -**TODO:** +* **BitTorrent Enhancement Process** as described in [BEP 1][bep-1]. +* **[Rust Language RFC Process][rust-rfc]** +* **[IETF RFC Process][ietf]** +* **[XMPP Standards Process][xmpp]** +* **Python Enhancement Process** documented in [PEP 1][pep-1]. + +[bep-1]: http://bittorrent.org/beps/bep_0001.html +[rust-rfc]: https://github.com/rust-lang/rfcs +[xmpp]: https://xmpp.org/about/standards-process.html +[ietf]: https://www.ietf.org/about/process-docs.html +[pep-1]: https://www.python.org/dev/peps/pep-0001/ # Unresolved questions [unresolved]: #unresolved-questions @@ -123,26 +181,16 @@ accepting or rejecting a given DEP? Optimistically, it would be clear from reading a PR discussion thread whether "consensus" has been reached or not, but this might be ambiguous or intimidating to first-time contributors. -When are or are not accepted DEPs binding? Presumably a technical DEP should -indicate whether it is optional or mandatory. - -Are "standard"/technical and "process" the right categories and terms to use? -Some DEP systems (like the IETF one) also use terminology like "informational" -(seems like we could rely on blog posts) an "normative". This might be helpful -for documenting things like peer discovery methods, which have intentially not -been specified as part of the formal spec (to make it clear that there is no -single "right way" to do discovery), but they should be documented somewhere. +The intention is to retroactively document the entire Dat protocol in the form +of DEPs, but the details and structure for this haven't been worked out. -Some communities eventually subsume the core protocol specification itself into -the DEP process (for example, the official Bittorrent protocol was documented -in a "BEP"). Should dat do this? Or rely on the current (and possibly future) -Dat whitepaper? +How mutable should Draft Standards DEPs be over time? What about Process DEPs? +Should there be an additional status ("Living"?) for DEPs that are expected to +evolve, or is this against the whole idea of having specific immutable +documents to reference? # Changelog [changelog]: #changelog -A brief statemnt about current status can go here, follow by a list of dates -when the status line of this DEP changed (in most-recent-last order). - - 2018-01-15: TODO: First complete draft submitted for review -- cgit v1.2.3 From 8a264d3393e226f13e220ac9185b946d6d69129b Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Fri, 19 Jan 2018 22:14:24 -0800 Subject: DEP-0001 changes in progress --- proposals/0001-dep-process.md | 263 ++++++++++++++++++++++++++++++------------ 1 file changed, 190 insertions(+), 73 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 29838ff..6d3dae9 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -7,9 +7,12 @@ Type: Process Status: Draft (as of 2018-01-15) -Github PR: [https://github.com/datprotocol/DEPs/pull/2]() +Github PR: [Draft](https://github.com/datprotocol/DEPs/pull/2) -Authors: TBD +Authors: Dat Protocol Working Group: Danielle, Mattias, Joe Hand, Karissa, +Paul, Tara, Bryan + +[Bryan Newbold](https://github.com/bnewbold) # Summary [summary]: #summary @@ -21,69 +24,82 @@ enhancements and organizational process. # Motivation [motivation]: #motivation -The community around the Dat protocol has grown to the point that standards -documentation and decision making centered around source code (an open -reference implementation) and a single whitepaper is insufficient. A specific -growing pain is the bandwidth of a small number of implementors to respond to -all informal proposals or requests for clarification on their own. - -A public DEP process is expected to increase the quality of core technical -protocols and library implementations (by clarifying changes early in the -process and allowing structured review by more individuals), lower the barrier -to additional implementations of the protocols (by clarifying implementation -details and norms not included in the core specification itself), and to make -the development process more transparent, accessible, and scalable to a growing -group of developers and end users. - -An additional goal of the process is to empower collaborators who are not core -Dat developers or paid staff to participate in community decision making around -protocols and process. Certain individuals will have special roles and -responsibilities, but should be less of a bottleneck or single-point-of-failure -for the ecosystem as a whole. +The Dat protocol is still a living standard. A transparent process is needed +for community members to understand what changes are in the pipeline and how +new ideas might come to fruition. + +The core protocol is being used and extended by several projects with differing +priorities and use cases. At the same time, lead developer time is very scarce. +There is a need to parallelize design and implementation work between projects, +which requires better coordination (process) and communication of technical +details (standards). There is also an increasing need to be legible to and +accessible to parties outside the existing Dat ecosystem. + +A public DEP process is expected to improve coordination and planning by +setting clear expectations for documentation of protocol changes and +extensions. The technical quality of the protocol itself should be improved by +increasing the number of people who can view and understand proposals at each +step of the process. The barrier to entry for independent implementations +should be lower, allowing new technical and user communities to adopt the +protocol. The overall developent and decision making process should be more +transparent, accessible, and scalable to a growing group of application +developers and end users # Submitting a Proposal [submit]: #submit -Before writing and proposing a DEP, which takes some time, it's best to -informally pitch your idea to see if others are already working on something -very similar, or if your idea has been discussed previously. This could take -place over chat, a short github issue, or any other medium. - -The process for proposing and debating a new DEP is: - -* Fork the [datprotocol/deps](https://github.com/datprotocol/deps) repository -* Copy `0000-template.md` to `proposals/0000-my-proposal.md` (don't chose the - "next" number, use zero; `my-proposal` should be a stub identifier for the - proposal) -* Fill in the DEP template. The more details you can fill in at the begining, - the more feedback reviewers can leave; on the other hand, the sooner you put - your ideas down in writing, the faster others can point out issues or related - efforts. Feel free to tweak or expand the structure (headers, content) of the - document to fit your needs. -* Submit a github pull request for discussion. The initial proposal will likely - be ammended based on review and comments. Go ahead and `cc:` specific - community members who you think would be good reviewers, though keep in mind - everybody's time and attention is finite.. -* Build interest and consensus. This part of the process will likely involve - both discussion on the PR comment thread and elsewhere (IRC, etc). -* Consider drafting or prototyping an implementation to demonstrate your - proposal and work out all the details. This step isn't strictly necessary, - however: a proposer does not need to be a developer. -* If the DEP is well-formed and there is sufficient interest (for or against - the proposal), a team member will assign an DEP number, update the status, - and merge the PR. Standards DEPs which need implementation or details to be - worked out, can be accepted as "Draft"; DEPs with strong acceptance can go - straight to "Active". -* A "Draft" DEP can be upgraded to "Active" after some time has passed and - confidence has been increased (eg, unresolved issues have been addressed, - implementations have been shown in the wild) by opening a PR for discussion - that sets the new Status. -* Small tweaks (grammar, clarifications) to a merged DEP can take place as - regular github PRs; revisiting or significantly revising should take place as - a new DEP. "Draft" and "Process" DEPs have a lower bar for evolution over - time via direct PR. - -All DEPs should have a type ("Standard" or "Process") and a status. +As a first step, before drafting a DEP or implementing experimental new +protocol features, it's helpful to informally pitch your idea to see if others +in the community are already thinking something similar, or have discussed the +same idea in the past. This discussion could happen over chat, github issues, +blog posts, or other channels. If you can recruit collaborators and work out +some of the details, all the better. This period could be called **pre-DEP**. + +Once your idea has been flushed out, the process for proposing and debating a +new DEP is: + +1. Use git to fork the [datprotocol/deps](https://github.com/datprotocol/deps) + repository +1. Copy `0000-template.md` to `proposals/0000-my-proposal.md` (don't chose the + "next" number, use zero; `my-proposal` should be a stub identifier for the + proposal) +1. Fill in the DEP template. All proposals should have a Type and Status (see + below for details). Feel free to tweak or expand the structure (headers, + content) of the document to fit your needs, but your proposal should be + "complete" before submission. +1. You can submit an informal WIP (work in progress) PR whenever you like for + early feedback and discussion, but there is no expectation that your + proposal will be given detailed review until it is complete. +1. When you are ready, submit your complete proposal for review (this could be + opening a PR or removing WIP status from an existing one). An editor will + look over your proposal for completeness; if acceptable, they will assign + one or more reviewers. At this stage, there are two primary outcomes: your + proposal is merged with "Draft", or declined. Submited proposals are + expected to be complete, understandable, and relevent; see below for more + details. This early stage of the review is expected to take **3 weeks at + most** from when reviewers were assigned. It is appropriate to propose + specific community members to review your proposal. The submiter can + withdraw a proposal at any time. If accepted, a DEP number will be assigned + and the PR merged. If there is unambiguous consensus (or, eg, a DEP is + documenting already adopted practice), a DEP can move directly to Active at + this stage. +1. While in draft status, proposals can be experimented with. Small corrections + and clarifications can be submitted by PR expect to be merged quickly if + they are reasonable and don't change the broad behavior or semantics of the + proposal; larger changes should be re-submitted as Superceding proposals. +1. When it seems approrpriate, a PR can be submitted to upgrade the status of a + Draft to Active. At this time a final review will take place, with the + outcome being that a prosal stays a Draft or is Active. It's also possible + for a Draft to be Closed (usuall by a specific PR to propose this). This + review period is shorter (**2 weeks maximum**), as the relevant reviewers + are expected to be familiar with the proposal at this point. Reasonably + sized changes to the DEP can be included, but it's expected that this is + in broad strokes the same proposal that was reviewed earlier (if not, a new + Draft should be proposed that Supercedes). +1. Small tweaks (grammar, clarifications) to a merged DEP can take place as + regular github PRs; revisiting or significantly revising should take place + as a new DEP. Draft, Process, and Informational DEPs have a lower bar for + evolution over time via direct PR. For appropriate DEPs (including *all* Standards DEPs), authors should explicitly consider and note impacts on: @@ -96,6 +112,7 @@ explicitly consider and note impacts on: [RFC-6973]: https://tools.ietf.org/html/rfc6973 [RFC-8280]: https://tools.ietf.org/html/rfc8280 + # Details [reference-documentation]: #reference-documentation @@ -117,7 +134,7 @@ The status of a DEP can be: "Status" line can list "Draft" when in this state. * **Draft**: PR has been merged and a number assigned, but additional time is needed for deeper discussion or more implementation before being fully - accepted. + adopted. * **Active**: adopted or intended for implementation in mainline libraries and clients as appropriate * **Closed**: either consensus was against, a decision was postponed, or the @@ -140,6 +157,84 @@ the Creative Commons Attribution License (CC-BY), with attribution to the major contributing authors listed. +# Adoption Criteria +[criteria]: #criteria + +The criteria for a proposal being accepted as a Draft are, at a minimum, that +the proposal is complete, understandable, unambiguous, and relevant. There is a +good faith assumption that the submiter believes that the proposal could +actually be adopted and put to beneficial use. An editor (any member of the +Protocol Working Group) screens proposals before to the group for review. + +For Standards and Process DEPs, Draft proposals should be specific enough that +it could be prototyped and experimented with (eg, a pilot program or test +network), but not that all details have been worked out. + +For a Draft to migrate to Active, there is an expectation that the proposal has +been demonstrated, that the change of significant unforseen issues in complete +adoption is low, and that the proposal will be the "new normal" and expected +behavior going forward. + + +# Decision Making Process +[power]: #power + +There exists a Protocol Working Group (WG) which makes DEP status decisions. +Membership is based on unanimous consensus invidation by the existing WG. WG +members can resign at and time, or be ejected by unanimous (by organization) +decision by the other WG members. Members are expected to commit to active +participation for 6 month windows. The WG is expected to respect the needs and +desires of the community as a whole. + +For Draft status, at leat one WG member must review the entire proposal in +detail, give feedback, and give informed approval. If no review takes place in +the fixed time window, the default is to close (reject) until a member is +willing to commit to review. Any WG member can request revisions or +clarifications (blocking acceptance until addressed) or veto acceptance if they +agree. A veto can be overridden by unanimous decision of all other WG members +on an organizational affiliation basis (aka: a single organization can not +unanimously veto a proposal). + +For Active status, the default is again negative (the proposal remains a +draft). + +Proposals are expected to be open for at least three days (72 hours) for +comment (and longer to accomodate special circumstances, like holidays). Vetos +can happen up to a week after initially being submitted for review, which might +be retroactive if the proposal was accepted early. + +For all other status changes, at least one WG member must vouch for or approve +the change. For example, if a Draft was submitted to be Closed, but the WG +decides to switch to Accept instead (!), only one WG member needs to propose +the change. If the WG is deadlocked (eg, conflicting proposals), the default +action is taken (which is no action). + + +# Rationale +[rationale]: #rationale + +This proposal attempts to head off a couple negative patterns. + +Proposals could get stuck in an ambiguous indefinite state anywhere along the +procoess, leaving ambiguity about their state. This is mitigated by setting +time limits and default outcomes. + +A related possible problem is when something is submitted for formal review, +but changes rapidly based on feedback, distracting reviewers and making it hard +to give clear feedback. Or, an incomplete proposal is submitted, reviewers ask +for more details, then need to re-review when the details arrive. This is +mitigated by setting expectations for the completeness of proposals before +submission, and giving an explicit "withdrawl and resubmit" workflow for larger +changes. + +When defining the proposal statuses, there are two manin questions for +technical standards: does draft status mean *could* be implemented, or *has* +been implemented? We chose "could". For active (or "final") status, is the +proposal *expected* to be dominant in the wild, or *is it already* dominant in +the wild? We chose "expected". In both cases we are emphasizing clarification +and stabilization of new ideas, as opposed to enforcing interoperability of +competing formulations of the same idea. + # Drawbacks [drawbacks]: #drawbacks @@ -154,6 +249,7 @@ another" place to look. [whitepaper]: https://github.com/datproject/docs/blob/master/papers/dat-paper.md [docs]: https://docs.datproject.org/ [datproto-group]: https://github.com/datprotocol +[discussion-repo]: https://github.com/datproject/discussions/issues # Background and References [references]: #references @@ -161,11 +257,32 @@ another" place to look. The following standards processes were referenced and considered while designing the DEP process: -* **BitTorrent Enhancement Process** as described in [BEP 1][bep-1]. -* **[Rust Language RFC Process][rust-rfc]** -* **[IETF RFC Process][ietf]** -* **[XMPP Standards Process][xmpp]** -* **Python Enhancement Process** documented in [PEP 1][pep-1]. +* **BitTorrent Enhancement Process** as described in [BEP 1][bep-1]. The + Bittorrent protocol has a lot of similarities to Dat, and as a "protocol" is + most similar in scope. +* The **[Rust Language RFC Process][rust-rfc]** is relatively new, but has had + a huge volume of proposals, rivaling even the IETF. The process is relatively + lightweight and happens entirely on Github; it is the most similar to the DEP + process proposed here. Rust has strong organizational backing with defined + leadership roles; proposals are reviewed by specific sub-teams. +* **[IETF RFC Process][ietf]**: perhaps the oldest and best known RFC process, + under the motto of "rough consensus and working code". The process is very + bespoke (involving custom file formats and software) and heavy on process + (with working groups and in-person meetings). +* **[XMPP Standards Process][xmpp]**: has the interesting sub-pattern of + regularly updated (annual) standards. XMPP is also a protocol, like + Bittorrent. The protocol was designed for easy extension, and at various + points has seen adoption, extention, and pressure from powerful entities. +* **Python Enhancement Process** documented in [PEP 1][pep-1]. PEPs are + relatively broad in scope (they often speak to process and organizational + dynamics), and are widely cited directly by name. Proposals are usually + debated in great detail on mailing lists before being proposed. Python has a + BDFL (benevolent dictator for life) who has final say over proposals, though + he sometimes delegates to deputies. +* The **W3C** is a paid membership organization which, like the IETF, is made + up of entities large and small, for-profit and altruistic, with decent + regional diversity. + [bep-1]: http://bittorrent.org/beps/bep_0001.html [rust-rfc]: https://github.com/rust-lang/rfcs @@ -176,17 +293,17 @@ designing the DEP process: # Unresolved questions [unresolved]: #unresolved-questions -Who are "core developers"? What is the specific decision making process for -accepting or rejecting a given DEP? Optimistically, it would be clear from -reading a PR discussion thread whether "consensus" has been reached or not, but -this might be ambiguous or intimidating to first-time contributors. +What is the specific decision making process for accepting or rejecting a given +DEP? Optimistically, it would be clear from reading a PR discussion thread +whether "consensus" has been reached or not, but this might be ambiguous or +intimidating to first-time contributors ("Tyrany of the Structureless"). The intention is to retroactively document the entire Dat protocol in the form -of DEPs, but the details and structure for this haven't been worked out. +of DEPs, but a specific plan for this hasn't been worked out yet. How mutable should Draft Standards DEPs be over time? What about Process DEPs? Should there be an additional status ("Living"?) for DEPs that are expected to -evolve, or is this against the whole idea of having specific immutable +evolve, or is this against the whole philosophy of having specific stable documents to reference? # Changelog -- cgit v1.2.3 From f60c8465ad0eb12ac1b08e7f55a5b4b9922f605d Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Fri, 19 Jan 2018 22:46:26 -0800 Subject: clarify unresolved status --- proposals/0001-dep-process.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 6d3dae9..75051d2 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -293,18 +293,18 @@ designing the DEP process: # Unresolved questions [unresolved]: #unresolved-questions -What is the specific decision making process for accepting or rejecting a given -DEP? Optimistically, it would be clear from reading a PR discussion thread -whether "consensus" has been reached or not, but this might be ambiguous or -intimidating to first-time contributors ("Tyrany of the Structureless"). +How is Working Group membership defined in the long run? This could be the +topic of a follow-on Process DEP while this DEP is in Draft status.. The intention is to retroactively document the entire Dat protocol in the form -of DEPs, but a specific plan for this hasn't been worked out yet. +of DEPs, but a specific plan for this hasn't been worked out yet. This is +expected to be tackled by the Working Group while this DEP is in Draft status. How mutable should Draft Standards DEPs be over time? What about Process DEPs? Should there be an additional status ("Living"?) for DEPs that are expected to evolve, or is this against the whole philosophy of having specific stable -documents to reference? +documents to reference? This is expected to be decided while this DEP is in +Draft status. # Changelog [changelog]: #changelog -- cgit v1.2.3 From 21d9bb27ec2e4ef91e0867fafff6a28e9eb4d0c5 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Fri, 19 Jan 2018 23:57:57 -0800 Subject: fix author name links --- proposals/0001-dep-process.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 75051d2..15c37dc 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -9,10 +9,9 @@ Status: Draft (as of 2018-01-15) Github PR: [Draft](https://github.com/datprotocol/DEPs/pull/2) -Authors: Dat Protocol Working Group: Danielle, Mattias, Joe Hand, Karissa, -Paul, Tara, Bryan - -[Bryan Newbold](https://github.com/bnewbold) +Authors: Dat Protocol Working Group: [Tara](https://github.com/taravancil), +[Paul](https://github.com/pfrazee), [Mathias](https://github.com/mafintosh), [Karissa](https://github.com/karissa), [Joe](https://github.com/karissa), [Danielle](#), +[Bryan](https://github.com/bnewbold) # Summary [summary]: #summary -- cgit v1.2.3 From 654d59dd7ae2e1bc8ec2e2132b9ebea2248531a5 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 09:17:46 -0800 Subject: add link to WG github repo --- proposals/0001-dep-process.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 15c37dc..d706e0b 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -9,10 +9,14 @@ Status: Draft (as of 2018-01-15) Github PR: [Draft](https://github.com/datprotocol/DEPs/pull/2) -Authors: Dat Protocol Working Group: [Tara](https://github.com/taravancil), -[Paul](https://github.com/pfrazee), [Mathias](https://github.com/mafintosh), [Karissa](https://github.com/karissa), [Joe](https://github.com/karissa), [Danielle](#), +Authors: [Dat Protocol Working Group][wg]: +[Tara](https://github.com/taravancil), [Paul](https://github.com/pfrazee), +[Mathias](https://github.com/mafintosh), [Karissa](https://github.com/karissa), +[Joe](https://github.com/karissa), [Danielle](#), [Bryan](https://github.com/bnewbold) +[wg]: https://github.com/datprotocol/working-group + # Summary [summary]: #summary @@ -178,12 +182,12 @@ behavior going forward. # Decision Making Process [power]: #power -There exists a Protocol Working Group (WG) which makes DEP status decisions. -Membership is based on unanimous consensus invidation by the existing WG. WG -members can resign at and time, or be ejected by unanimous (by organization) -decision by the other WG members. Members are expected to commit to active -participation for 6 month windows. The WG is expected to respect the needs and -desires of the community as a whole. +There exists a [Protocol Working Group (WG)][wg] which makes DEP status +decisions. Membership is based on unanimous consensus invidation by the +existing WG. WG members can resign at and time, or be ejected by unanimous (by +organization) decision by the other WG members. Members are expected to commit +to active participation for 6 month windows. The WG is expected to respect the +needs and desires of the community as a whole. For Draft status, at leat one WG member must review the entire proposal in detail, give feedback, and give informed approval. If no review takes place in -- cgit v1.2.3 From a34d23e800b3f45218da59ef00d3378d26eb2a5a Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 22:43:54 -0800 Subject: full WG member names --- proposals/0001-dep-process.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index d706e0b..1983b08 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -10,13 +10,17 @@ Status: Draft (as of 2018-01-15) Github PR: [Draft](https://github.com/datprotocol/DEPs/pull/2) Authors: [Dat Protocol Working Group][wg]: -[Tara](https://github.com/taravancil), [Paul](https://github.com/pfrazee), -[Mathias](https://github.com/mafintosh), [Karissa](https://github.com/karissa), -[Joe](https://github.com/karissa), [Danielle](#), -[Bryan](https://github.com/bnewbold) +[Tara Vancil](https://github.com/taravancil), +[Paul Frazee](https://github.com/pfrazee), +[Mathias Buus](https://github.com/mafintosh), +[Karissa McKelvey](https://github.com/karissa), +[Joe Hand](https://github.com/karissa), +[Danielle Robinson](#), +[Bryan Newbold](https://github.com/bnewbold) [wg]: https://github.com/datprotocol/working-group + # Summary [summary]: #summary @@ -24,6 +28,7 @@ The Dat Enhancement Proposal ("DEP") process is how the Dat open source community comes to (distributed) consensus around technical protocol enhancements and organizational process. + # Motivation [motivation]: #motivation -- cgit v1.2.3 From dbb215ecf74efb847a0ff6d28fc7cc2b48c99f05 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 22:44:52 -0800 Subject: restructure --- proposals/0001-dep-process.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 1983b08..de36f8f 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -53,13 +53,14 @@ protocol. The overall developent and decision making process should be more transparent, accessible, and scalable to a growing group of application developers and end users -# Submitting a Proposal + +# How To Submit a Proposal [submit]: #submit As a first step, before drafting a DEP or implementing experimental new protocol features, it's helpful to informally pitch your idea to see if others in the community are already thinking something similar, or have discussed the -same idea in the past. This discussion could happen over chat, github issues, +same idea in the past. This discussion could happen over chat, Github issues, blog posts, or other channels. If you can recruit collaborators and work out some of the details, all the better. This period could be called **pre-DEP**. @@ -109,21 +110,12 @@ new DEP is: as a new DEP. Draft, Process, and Informational DEPs have a lower bar for evolution over time via direct PR. -For appropriate DEPs (including *all* Standards DEPs), authors should -explicitly consider and note impacts on: - -* Privacy and User Rights: consider reading IETF [RFC 6973] ("Privacy - Considerations for Internet Protocols") and [RFC 8280] ("Research into Human - Rights Protocol Considerations") -* Backwards compatibility of on-disk archives and older network clients - -[RFC-6973]: https://tools.ietf.org/html/rfc6973 -[RFC-8280]: https://tools.ietf.org/html/rfc8280 - - # Details [reference-documentation]: #reference-documentation +## Types and Statuses +[types]: #types + DEPs should have a type: * **Standard** for technical changes to the protocol, on-disk formats, or @@ -154,6 +146,9 @@ The status of a DEP can be: active DEP; the new DEP should specify specific old DEPs that it would supersede. +## Content and Structure +[content]: #content + A changelog should be kept in the DEP itself giving the date of any changes of status. @@ -259,6 +254,7 @@ another" place to look. [datproto-group]: https://github.com/datprotocol [discussion-repo]: https://github.com/datproject/discussions/issues + # Background and References [references]: #references @@ -298,6 +294,7 @@ designing the DEP process: [ietf]: https://www.ietf.org/about/process-docs.html [pep-1]: https://www.python.org/dev/peps/pep-0001/ + # Unresolved questions [unresolved]: #unresolved-questions -- cgit v1.2.3 From a641c5f30b8f1a82d6486bb03ec05b03cad8ab30 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 22:45:20 -0800 Subject: editing, clarify, WF meeting feedback --- proposals/0001-dep-process.md | 230 ++++++++++++++++++++++++------------------ 1 file changed, 130 insertions(+), 100 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index de36f8f..2897163 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -76,37 +76,37 @@ new DEP is: below for details). Feel free to tweak or expand the structure (headers, content) of the document to fit your needs, but your proposal should be "complete" before submission. -1. You can submit an informal WIP (work in progress) PR whenever you like for - early feedback and discussion, but there is no expectation that your - proposal will be given detailed review until it is complete. +1. You can create an informal WIP (work in progress) PR (pull-request) + whenever you like for early feedback and discussion, but there is no + expectation that your proposal will be given detailed review until it is + complete. 1. When you are ready, submit your complete proposal for review (this could be - opening a PR or removing WIP status from an existing one). An editor will - look over your proposal for completeness; if acceptable, they will assign - one or more reviewers. At this stage, there are two primary outcomes: your - proposal is merged with "Draft", or declined. Submited proposals are - expected to be complete, understandable, and relevent; see below for more - details. This early stage of the review is expected to take **3 weeks at - most** from when reviewers were assigned. It is appropriate to propose - specific community members to review your proposal. The submiter can - withdraw a proposal at any time. If accepted, a DEP number will be assigned - and the PR merged. If there is unambiguous consensus (or, eg, a DEP is - documenting already adopted practice), a DEP can move directly to Active at - this stage. + opening a PR or removing WIP status from an existing one), with the intent + of being accepted with "Draft" status. + An editor (somebody who is an owner of the DEPs repository) will look over + your proposal for completeness; if acceptable, they will assign one or more + reviewers. + At this stage, two outcomes are the most likely: your proposal + is merged with "Draft" status, or declined. This first stage of the review + is expected to take **3 weeks at most** from when reviewers were assigned. + It is appropriate to propose specific community members to review your + proposal. The submiter can withdraw a proposal at any time. If accepted, a + DEP number will be assigned and the PR merged. If declined, reviewers may + give feedback and/or invite proposers to "significantly revise and resubmit". 1. While in draft status, proposals can be experimented with. Small corrections and clarifications can be submitted by PR expect to be merged quickly if they are reasonable and don't change the broad behavior or semantics of the proposal; larger changes should be re-submitted as Superceding proposals. 1. When it seems approrpriate, a PR can be submitted to upgrade the status of a - Draft to Active. At this time a final review will take place, with the - outcome being that a prosal stays a Draft or is Active. It's also possible - for a Draft to be Closed (usuall by a specific PR to propose this). This - review period is shorter (**2 weeks maximum**), as the relevant reviewers - are expected to be familiar with the proposal at this point. Reasonably - sized changes to the DEP can be included, but it's expected that this is - in broad strokes the same proposal that was reviewed earlier (if not, a new - Draft should be proposed that Supercedes). + "Draft" to "Active". At this time a final review will take place, with the + outcome being that a proposal stays "Draft" or becomes "Active". + This review period is shorter (**2 weeks at most**), as everybody is + expected to be more familiar with the proposal at this point. + Small changes to the DEP can be included, but it's expected that + this is in broad strokes the same proposal that was reviewed earlier (if + not, a new "Draft" should be proposed that Supercedes). 1. Small tweaks (grammar, clarifications) to a merged DEP can take place as - regular github PRs; revisiting or significantly revising should take place + regular Github PRs; revisiting or significantly revising should take place as a new DEP. Draft, Process, and Informational DEPs have a lower bar for evolution over time via direct PR. @@ -131,19 +131,21 @@ DEPs should have a type: The status of a DEP can be: * **Pre-Merge**: a well-formed DEP has been written and a PR opened. The - "Status" line can list "Draft" when in this state. + "Status" line can list Draft when in this state. * **Draft**: PR has been merged and a number assigned, but additional time is - needed for deeper discussion or more implementation before being fully - adopted. + needed for deeper discussion or more implementation before being "normative" + and expected for implementation. It is acceptable to have "competing" + proposals in this state at the same time. * **Active**: adopted or intended for implementation in mainline libraries and - clients as appropriate + clients as appropriate. Again, DEPs should clarify which aspects of + themselves are optional or required for well-behaved clients. * **Closed**: either consensus was against, a decision was postponed, or the authors withdrew their proposal. This could apply to any of: a proposal PR that was never merged, a merged Draft (which was never Active), or an Active DEP which there is now consensus against without a specific new DEP to replace it. -* **Superseded**: a formerly "active" DEP has been made obsolete by a new - active DEP; the new DEP should specify specific old DEPs that it would +* **Superseded**: a formerly Active DEP has been made obsolete by a new + Active DEP; the new DEP should specify specific old DEPs that it would supersede. ## Content and Structure @@ -159,84 +161,108 @@ The DEP text itself should be permissively licensed; the convention is to use the Creative Commons Attribution License (CC-BY), with attribution to the major contributing authors listed. +For appropriate DEPs (including *all* Standards DEPs), authors should +explicitly consider and note impacts on: -# Adoption Criteria +* Privacy and User Rights. Consider reading IETF [RFC 6973] ("Privacy + Considerations for Internet Protocols") and [RFC 8280] ("Research into Human + Rights Protocol Considerations") +* Backwards compatibility of on-disk archives and older network clients. If a + backwards-incompatible change is proposed, a migration plan should be + sketched out in the proposal +* Security + +[RFC-6973]: https://tools.ietf.org/html/rfc6973 +[RFC-8280]: https://tools.ietf.org/html/rfc8280 + + +## Acceptance Criteria [criteria]: #criteria The criteria for a proposal being accepted as a Draft are, at a minimum, that the proposal is complete, understandable, unambiguous, and relevant. There is a good faith assumption that the submiter believes that the proposal could -actually be adopted and put to beneficial use. An editor (any member of the -Protocol Working Group) screens proposals before to the group for review. +actually be adopted and put to beneficial use. An editor screens proposals +before fothe group for review. For Standards and Process DEPs, Draft proposals should be specific enough that -it could be prototyped and experimented with (eg, a pilot program or test -network), but not that all details have been worked out. +they can be prototyped and experimented with (eg, in a pilot program or test +network), but it isn't expected that all details have been worked out. Working +code is helpful but not required. For a Draft to migrate to Active, there is an expectation that the proposal has -been demonstrated, that the change of significant unforseen issues in complete -adoption is low, and that the proposal will be the "new normal" and expected -behavior going forward. +been demonstrated (eg, in working code, though not necessarily in "official" +libraries yet), that the proposal will be the "new normal" and expected +behavior going forward, and that the chance of unforseen issues arising during +complete adoption is low. -# Decision Making Process +## Decision Making Process [power]: #power -There exists a [Protocol Working Group (WG)][wg] which makes DEP status -decisions. Membership is based on unanimous consensus invidation by the -existing WG. WG members can resign at and time, or be ejected by unanimous (by -organization) decision by the other WG members. Members are expected to commit -to active participation for 6 month windows. The WG is expected to respect the -needs and desires of the community as a whole. - -For Draft status, at leat one WG member must review the entire proposal in -detail, give feedback, and give informed approval. If no review takes place in -the fixed time window, the default is to close (reject) until a member is -willing to commit to review. Any WG member can request revisions or -clarifications (blocking acceptance until addressed) or veto acceptance if they -agree. A veto can be overridden by unanimous decision of all other WG members -on an organizational affiliation basis (aka: a single organization can not -unanimously veto a proposal). - -For Active status, the default is again negative (the proposal remains a -draft). +There exists a [Protocol Working Group (WG)][wg] (WG) which makes DEP status +decisions; see the Github repository for a list of current members and the +governance process. -Proposals are expected to be open for at least three days (72 hours) for -comment (and longer to accomodate special circumstances, like holidays). Vetos -can happen up to a week after initially being submitted for review, which might -be retroactive if the proposal was accepted early. +By no means should working group members be the only people reviewing or giving +feedback on proposals. + +When deciding on Draft status, at least one WG member must review the entire +proposal in detail, give feedback, and give informed approval. If no detailed +review takes place in the fixed time window, the default is to close (reject) +until a member is willing to commit to review. Any WG member can request +revisions or clarifications (blocking acceptance until addressed), and any +member can block. In other words, consensus requires that at least one member +actively approve, and any member can block, but it isn't required to have every +member review and actively given an opinion. This is referred to as the "loose +consensus" model. + +For Active status, the expectation is that all working group members will +review the proposal and actively participate in consensus. In the event that +not all members can participate, the default is again negative. Any member can +block. This is referred to as the "complete consensus" model. For all other status changes, at least one WG member must vouch for or approve -the change. For example, if a Draft was submitted to be Closed, but the WG -decides to switch to Accept instead (!), only one WG member needs to propose -the change. If the WG is deadlocked (eg, conflicting proposals), the default -action is taken (which is no action). +the change ("loose consensus"). If there is unambiguous consensus (or, eg, a +DEP is documenting already adopted practice), a DEP can move directly to Active +status (following the "complete consensus" process). + +In all cases, if there is a deadlock (a block can not be overcome after +further discussion), there is an option to override the block by a vote. The +details of this process are left to description in the Working Group +repository, and are expected to be used only in exceptional cases (eg, are not +invoked by default if a member blocks). + +Proposals are expected to be open for at least three days (72 hours) for +comment (and longer to accomodate special circumstances, like holidays). Vetos +(blocks) can happen up to a week after initially being submitted for review, +which might be retroactive if the proposal was accepted (by other WG members) +very quickly. # Rationale [rationale]: #rationale -This proposal attempts to head off a couple negative patterns. +In the design space of RFC processes, there are two decision points determining +the formality and maturity of accepted standards. The first is, does draft +status mean *could* be implemented, or *has* been implemented? We chose +"could". Secondly, for active (or "final") status, is the proposal *expected* +to be dominant in the wild, or *is it already* dominant in the wild? We chose +"expected". In both cases we are emphasizing clarification and stabilization of +new ideas, as opposed to enforcing interoperability of competing formulations +of the same idea. In short, we expect DEPs to lead (rather than tail) +implementation. -Proposals could get stuck in an ambiguous indefinite state anywhere along the -procoess, leaving ambiguity about their state. This is mitigated by setting -time limits and default outcomes. +Time limits and default outcomes are used to prevent proposals could get stuck +in an ambiguous indefinite state anywhere along the process. "Draft" status is +considered a stable state to linger in. -A related possible problem is when something is submitted for formal review, -but changes rapidly based on feedback, distracting reviewers and making it hard -to give clear feedback. Or, an incomplete proposal is submitted, reviewers ask -for more details, then need to re-review when the details arrive. This is -mitigated by setting expectations for the completeness of proposals before -submission, and giving an explicit "withdrawl and resubmit" workflow for larger -changes. +Setting expectations for "completeness" of proposals, having an editor quickly +skim proposals before jumping in to a full review, and acknowleding an explicit +"revise and re-submit" workflow are all attempts to head off the situation of +partial proposals being submitted and then significantly revised, which places +extra (time) burden on reviewers. -When defining the proposal statuses, there are two manin questions for -technical standards: does draft status mean *could* be implemented, or *has* -been implemented? We chose "could". For active (or "final") status, is the -proposal *expected* to be dominant in the wild, or *is it already* dominant in -the wild? We chose "expected". In both cases we are emphasizing clarification -and stabilization of new ideas, as opposed to enforcing interoperability of -competing formulations of the same idea. # Drawbacks [drawbacks]: #drawbacks @@ -262,13 +288,18 @@ The following standards processes were referenced and considered while designing the DEP process: * **BitTorrent Enhancement Process** as described in [BEP 1][bep-1]. The - Bittorrent protocol has a lot of similarities to Dat, and as a "protocol" is - most similar in scope. + Bittorrent protocol has a lot of technical similarities to Dat, and as a + single protocol family (not a language or full-stack system) is one of the + most similar in scope. The de facto BEP model is that Drafts are very stable + and widely adopted; only the most universal core components are Final. The + DEP process bases it's type categories on the BEP process. There is a single + editor and an explicit BDFL in the BEP process. * The **[Rust Language RFC Process][rust-rfc]** is relatively new, but has had a huge volume of proposals, rivaling even the IETF. The process is relatively lightweight and happens entirely on Github; it is the most similar to the DEP - process proposed here. Rust has strong organizational backing with defined - leadership roles; proposals are reviewed by specific sub-teams. + process proposed here, in terms of Draft/Active distinction. Rust has strong + organizational backing with defined leadership roles; proposals are reviewed + by specific sub-teams. * **[IETF RFC Process][ietf]**: perhaps the oldest and best known RFC process, under the motto of "rough consensus and working code". The process is very bespoke (involving custom file formats and software) and heavy on process @@ -285,7 +316,8 @@ designing the DEP process: he sometimes delegates to deputies. * The **W3C** is a paid membership organization which, like the IETF, is made up of entities large and small, for-profit and altruistic, with decent - regional diversity. + regional diversity. W3C standards are often rather large and verbose + documents, and tend to tail (rather than lead) implementation. [bep-1]: http://bittorrent.org/beps/bep_0001.html @@ -298,21 +330,19 @@ designing the DEP process: # Unresolved questions [unresolved]: #unresolved-questions -How is Working Group membership defined in the long run? This could be the -topic of a follow-on Process DEP while this DEP is in Draft status.. - -The intention is to retroactively document the entire Dat protocol in the form -of DEPs, but a specific plan for this hasn't been worked out yet. This is -expected to be tackled by the Working Group while this DEP is in Draft status. +How mutable should "Draft" Standards DEPs be over time? What about +Informational DEPs? Should there be an additional status ("Living"?) for DEPs +that are expected to evolve, or is this against the whole philosophy of having +specific stable documents to reference? This is expected to be clarified while +this DEP itself is in Draft status. -How mutable should Draft Standards DEPs be over time? What about Process DEPs? -Should there be an additional status ("Living"?) for DEPs that are expected to -evolve, or is this against the whole philosophy of having specific stable -documents to reference? This is expected to be decided while this DEP is in -Draft status. +Does "Active" status mean that implementation is *mandatory*, and that features +*must* be implemented unless they are explicitly optional? How would this +expectation be enforced for third-party software? This is expected to be +clarified when concrete examples arise. # Changelog [changelog]: #changelog -- 2018-01-15: TODO: First complete draft submitted for review +- 2018-01-24: DEP process and governance model is discussed by Working Group -- cgit v1.2.3 From aaea50f2248d4f7e013b01d27b0972cd8fa25d8c Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 22:51:56 -0800 Subject: spellcheck and tweak for submission --- proposals/0001-dep-process.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 2897163..d0ccf40 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -5,7 +5,7 @@ Short Name: `0001-dep-process` Type: Process -Status: Draft (as of 2018-01-15) +Status: Draft (as of 2018-XX-YY) Github PR: [Draft](https://github.com/datprotocol/DEPs/pull/2) @@ -49,7 +49,7 @@ extensions. The technical quality of the protocol itself should be improved by increasing the number of people who can view and understand proposals at each step of the process. The barrier to entry for independent implementations should be lower, allowing new technical and user communities to adopt the -protocol. The overall developent and decision making process should be more +protocol. The overall development and decision making process should be more transparent, accessible, and scalable to a growing group of application developers and end users @@ -90,21 +90,21 @@ new DEP is: is merged with "Draft" status, or declined. This first stage of the review is expected to take **3 weeks at most** from when reviewers were assigned. It is appropriate to propose specific community members to review your - proposal. The submiter can withdraw a proposal at any time. If accepted, a + proposal. The submitter can withdraw a proposal at any time. If accepted, a DEP number will be assigned and the PR merged. If declined, reviewers may give feedback and/or invite proposers to "significantly revise and resubmit". 1. While in draft status, proposals can be experimented with. Small corrections and clarifications can be submitted by PR expect to be merged quickly if they are reasonable and don't change the broad behavior or semantics of the - proposal; larger changes should be re-submitted as Superceding proposals. -1. When it seems approrpriate, a PR can be submitted to upgrade the status of a + proposal; larger changes should be re-submitted as Superseding proposals. +1. When it seems appropriate, a PR can be submitted to upgrade the status of a "Draft" to "Active". At this time a final review will take place, with the outcome being that a proposal stays "Draft" or becomes "Active". This review period is shorter (**2 weeks at most**), as everybody is expected to be more familiar with the proposal at this point. Small changes to the DEP can be included, but it's expected that this is in broad strokes the same proposal that was reviewed earlier (if - not, a new "Draft" should be proposed that Supercedes). + not, a new "Draft" should be proposed that Supersedes). 1. Small tweaks (grammar, clarifications) to a merged DEP can take place as regular Github PRs; revisiting or significantly revising should take place as a new DEP. Draft, Process, and Informational DEPs have a lower bar for @@ -119,7 +119,7 @@ new DEP is: DEPs should have a type: * **Standard** for technical changes to the protocol, on-disk formats, or - public APIs. These are intented to be *proscriptive*, and to clearly + public APIs. These are intended to be *proscriptive*, and to clearly delineate which features and behaviors are mandatory or optional. * **Process** for formalizing community processes or other (technical or non-technical) decisions. For example, a security vulnerability reporting @@ -181,9 +181,9 @@ explicitly consider and note impacts on: The criteria for a proposal being accepted as a Draft are, at a minimum, that the proposal is complete, understandable, unambiguous, and relevant. There is a -good faith assumption that the submiter believes that the proposal could -actually be adopted and put to beneficial use. An editor screens proposals -before fothe group for review. +good faith assumption that the submitter believes that the proposal could +actually be adopted and put to beneficial use. An editor may screen proposals +before passing on to the group for review. For Standards and Process DEPs, Draft proposals should be specific enough that they can be prototyped and experimented with (eg, in a pilot program or test @@ -193,7 +193,7 @@ code is helpful but not required. For a Draft to migrate to Active, there is an expectation that the proposal has been demonstrated (eg, in working code, though not necessarily in "official" libraries yet), that the proposal will be the "new normal" and expected -behavior going forward, and that the chance of unforseen issues arising during +behavior going forward, and that the chance of unforeseen issues arising during complete adoption is low. @@ -234,7 +234,7 @@ repository, and are expected to be used only in exceptional cases (eg, are not invoked by default if a member blocks). Proposals are expected to be open for at least three days (72 hours) for -comment (and longer to accomodate special circumstances, like holidays). Vetos +comment (and longer to accommodate special circumstances, like holidays). Vetoes (blocks) can happen up to a week after initially being submitted for review, which might be retroactive if the proposal was accepted (by other WG members) very quickly. @@ -258,7 +258,7 @@ in an ambiguous indefinite state anywhere along the process. "Draft" status is considered a stable state to linger in. Setting expectations for "completeness" of proposals, having an editor quickly -skim proposals before jumping in to a full review, and acknowleding an explicit +skim proposals before jumping in to a full review, and acknowledging an explicit "revise and re-submit" workflow are all attempts to head off the situation of partial proposals being submitted and then significantly revised, which places extra (time) burden on reviewers. @@ -307,7 +307,7 @@ designing the DEP process: * **[XMPP Standards Process][xmpp]**: has the interesting sub-pattern of regularly updated (annual) standards. XMPP is also a protocol, like Bittorrent. The protocol was designed for easy extension, and at various - points has seen adoption, extention, and pressure from powerful entities. + points has seen adoption, extension, and pressure from powerful entities. * **Python Enhancement Process** documented in [PEP 1][pep-1]. PEPs are relatively broad in scope (they often speak to process and organizational dynamics), and are widely cited directly by name. Proposals are usually @@ -344,5 +344,6 @@ clarified when concrete examples arise. # Changelog [changelog]: #changelog -- 2018-01-24: DEP process and governance model is discussed by Working Group +- 2018-01-24: DEP process and governance model is discussed by Working Group. + First full draft of DEP-0001 submitted for review. -- cgit v1.2.3 From 1042de34b2cc25ea02eeb3ede39e7c8146c4b9c0 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 23:02:31 -0800 Subject: add version changes as a motivation --- proposals/0001-dep-process.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index d0ccf40..963ed14 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -43,6 +43,11 @@ which requires better coordination (process) and communication of technical details (standards). There is also an increasing need to be legible to and accessible to parties outside the existing Dat ecosystem. +With growing use, the logistics of rolling out protocol changes and +backwards-incompatible changes becomes more difficult, but at the same time +more important to coordinate smoothly. Planning requires clear communication of +change ahead of time. + A public DEP process is expected to improve coordination and planning by setting clear expectations for documentation of protocol changes and extensions. The technical quality of the protocol itself should be improved by -- cgit v1.2.3 From feea3cb44beaaa013e55b67609a0f96902cf4127 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Tue, 30 Jan 2018 10:43:11 -0800 Subject: fix author github URLs Thanks joehand! --- proposals/0001-dep-process.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'proposals') diff --git a/proposals/0001-dep-process.md b/proposals/0001-dep-process.md index 963ed14..29b557e 100644 --- a/proposals/0001-dep-process.md +++ b/proposals/0001-dep-process.md @@ -14,8 +14,8 @@ Authors: [Dat Protocol Working Group][wg]: [Paul Frazee](https://github.com/pfrazee), [Mathias Buus](https://github.com/mafintosh), [Karissa McKelvey](https://github.com/karissa), -[Joe Hand](https://github.com/karissa), -[Danielle Robinson](#), +[Joe Hand](https://github.com/joehand), +[Danielle Robinson](https://github.com/daniellecrobinson), [Bryan Newbold](https://github.com/bnewbold) [wg]: https://github.com/datprotocol/working-group -- cgit v1.2.3