1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
Title: **DEP-0001: The Dat Enhancement Proposal Process**
Short Name: `0001-dep-process`
Type: Process
Status: Draft (as of 2018-01-15)
Github PR: (add HTTPS link here after PR is opened)
# Summary
[summary]: #summary
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
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 `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 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).
* 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.
* 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 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.
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?
# 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
|
