aboutsummaryrefslogtreecommitdiffstats
path: root/proposals
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2018-01-10 21:14:46 -0800
committerBryan Newbold <bnewbold@robocracy.org>2018-01-10 21:14:46 -0800
commita66e7b77d4c3c8ad90022af8bae31094e2bb929b (patch)
treece8e0d7a6b3dec08f3f0b80dc6ce458d89cac6be /proposals
parent9c81ab3e9129c0f462c17ad1c237b87213a68b07 (diff)
downloaddat-deps-a66e7b77d4c3c8ad90022af8bae31094e2bb929b.tar.gz
dat-deps-a66e7b77d4c3c8ad90022af8bae31094e2bb929b.zip
first draft template and DEP-0001
Diffstat (limited to 'proposals')
-rw-r--r--proposals/0001-dep-process.md147
1 files changed, 147 insertions, 0 deletions
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
+