document RFC process and add a template

2 files changed, 110 insertions, 0 deletions

diff --git a/rfcs/README.md b/rfcs/README.md
new file mode 100644
index 0000000..0b72646
--- /dev/null
+++ b/rfcs/README.md
@@ -0,0 +1,61 @@
+
+This folder (part of the `dat-docs` repository at
+https://github.com/datproject/dat-docs) contains a series of proposed (and
+eventually accepted) "Requests for Comment" (RFC) documents for the Dat
+Protocol and ecosystem.
+
+For now this process is as simple and informal; as the number of dat developers
+and users grows, it may become more formal. Inspirations for this process
+include:
+
+- [Bittorrent Enhancement Proposals (BEP)](http://bittorrent.org/beps/bep_0001.html)
+- [Rust RFC Process](https://github.com/rust-lang/rfcs)
+- [Python Enhancement Proposal](https://www.python.org/dev/peps/pep-0001/)
+
+
+## The Process
+
+TL;DR: write up an RFC
+
+* Fork this git repository
+* Copy `rfcs/template.md` to `text/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 RFC 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
+  RFC 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 RFC number, update the status, and merge the PR.
+* Small tweaks (grammar, clarifications) to a merged RFC can take place as
+  regular github PRs; revisiting or significantly revising should take place as
+  a new RFC.
+
+RFCs 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 RFC 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" RFC has been made obsolete by a new
+  active RFC; the new RFC should specify specific old RFCs that it would
+  supersede.
+
diff --git a/rfcs/template.md b/rfcs/template.md
new file mode 100644
index 0000000..78fdeb9
--- /dev/null
+++ b/rfcs/template.md
@@ -0,0 +1,49 @@
+
+Status: Undefined (as of YYY-MM-DD)
+
+Type: (Standard or Process)
+
+Github PR: (add HTTPS link here after PR is opened)
+
+Short Name: (number and shortname here, like `0000-my-proposal`)
+
+# 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 RFC 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 RFC that could be addressed in the future independently of the solution that comes out of this RFC?