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 --- 0000-template.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 0000-template.md (limited to '0000-template.md') diff --git a/0000-template.md b/0000-template.md new file mode 100644 index 0000000..1592ade --- /dev/null +++ b/0000-template.md @@ -0,0 +1,59 @@ + +Title: **DEP 0000: My Proposal** + +Short Name: `0000-my-proposal` + +Type: (Standard or Process) + +Status: Undefined (as of YYYY-MM-DD) + +Github PR: (add HTTPS link here after PR is opened) + +# Summary +[summary]: #summary + +One paragraph explanation of what this is about. + +# Motivation +[motivation]: #motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +# Usage Documentation +[usage-documentation]: #usage-documentation + +Document new features or processes as if this proposal has already been accepted and implemented. This section should introduce new concepts and terms, describe use cases or situations, and provide examples. If a user-facing feature is added, this should also include user-accessible documentation. + +# Reference Documentation +[reference-documentation]: #reference-documentation + +This section is a more formal description of the proposal, written as if it was a sub-section of the standard (for techincal proposals) or a formal process or "fine print" for process proposals. + +It should be unambiguous and cover all known corner-cases. Formal language (such as protobuf schemas or binary header diagrams) are appropriate here. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? + +# Rationale and alternatives +[alternatives]: #alternatives + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? + +# Unresolved questions +[unresolved]: #unresolved-questions + +- What parts of the design do you expect to resolve through the DEP consensus process before this gets merged? +- What parts of the design do you expect to resolve through implementation and code review, or are left to independent library or application developers? +- What related issues do you consider out of scope for this DEP that could be addressed in the future independently of the solution that comes out of this DEP? + +# 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). + +- YYYY-MM-DD: First complete draft submitted for review -- cgit v1.2.3 From 52b0a7ab5c6bc8febb9dde1722c05cd98bf6d177 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Mon, 15 Jan 2018 23:42:02 -0800 Subject: syntax tweaks in README and template --- 0000-template.md | 2 +- README.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) (limited to '0000-template.md') diff --git a/0000-template.md b/0000-template.md index 1592ade..8b746e5 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,5 +1,5 @@ -Title: **DEP 0000: My Proposal** +Title: **DEP-0000: My Proposal** Short Name: `0000-my-proposal` diff --git a/README.md b/README.md index e5f8235..0bbe2b1 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,17 @@ This repository contains a series of "Dat Enhancement Proposal" (DEP) documents, part of the dat protocol development and standardization process. -Accepted proposals can be viewed at [datprotocol.com](https://datprotocol.com). +Accepted proposals will be viewable at [datprotocol.com](https://datprotocol.com). New (draft) proposals and discussion can be viewed on [github][github-deps] under "issues" and "pull-requests". These documents might be interesting reading to anybody wanting to learn more about protocol nitty gritties or the consensus process, but the documentation -at [https://docs.datproject.org]() is specifically written with end-users and +at [docs.datproject.org][docs] is specifically written with end-users and application developers in mind. [github-deps]: https://github.com/datprotocol/DEPs/ +[docs]: https://docs.datproject.com ## The Process -- 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 '0000-template.md') 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 792b681d3633af9ad17a351b6957fcf5cbab5796 Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Wed, 24 Jan 2018 22:45:45 -0800 Subject: small tweaks to template --- 0000-template.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to '0000-template.md') diff --git a/0000-template.md b/0000-template.md index b269b1c..bea1fae 100644 --- a/0000-template.md +++ b/0000-template.md @@ -11,21 +11,25 @@ Github PR: (add HTTPS link here after PR is opened) Authors: TBD + # Summary [summary]: #summary One paragraph explanation of what this is about. + # Motivation [motivation]: #motivation Why are we doing this? What use cases does it support? What is the expected outcome? + # Usage Documentation [usage-documentation]: #usage-documentation Document new features or processes as if this proposal has already been accepted and implemented. This section should introduce new concepts and terms, describe use cases or situations, and provide examples. If a user-facing feature is added, this should also include user-accessible documentation. + # Reference Documentation [reference-documentation]: #reference-documentation @@ -33,11 +37,15 @@ This section is a more formal description of the proposal, written as if it was It should be unambiguous and cover all known corner-cases. Formal language (such as protobuf schemas or binary header diagrams) are appropriate here. +"Standards" proposals should include a section addressing security and privacy implications. + + # Drawbacks [drawbacks]: #drawbacks Why should we *not* do this? + # Rationale and alternatives [alternatives]: #alternatives @@ -45,6 +53,7 @@ Why should we *not* do this? - What other designs have been considered and what is the rationale for not choosing them? - What is the impact of not doing this? + # Unresolved questions [unresolved]: #unresolved-questions @@ -52,6 +61,7 @@ Why should we *not* do this? - What parts of the design do you expect to resolve through implementation and code review, or are left to independent library or application developers? - What related issues do you consider out of scope for this DEP that could be addressed in the future independently of the solution that comes out of this DEP? + # Changelog [changelog]: #changelog @@ -59,3 +69,4 @@ 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). - YYYY-MM-DD: First complete draft submitted for review + -- cgit v1.2.3