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 +++++++++++++++++ proposals/0001-dep-process.md | 147 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 206 insertions(+) create mode 100644 0000-template.md create mode 100644 proposals/0001-dep-process.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 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