From 2c0db47409b9dde8ac2e19da8008a16b6427c84c Mon Sep 17 00:00:00 2001
From: str4d <str4d@mail.i2p>
Date: Mon, 25 Apr 2016 04:35:30 +0000
Subject: [PATCH] Proposal process document
Derived from the torspec proposal process document. Currently licensed under
3-clause BSD pending relicensing:
https://trac.torproject.org/projects/tor/ticket/18788
---
LICENSE.txt | 2 +
i2p2www/spec/proposals/001-process.rst | 267 +++++++++++++++++++++++++
2 files changed, 269 insertions(+)
create mode 100644 i2p2www/spec/proposals/001-process.rst
diff --git a/LICENSE.txt b/LICENSE.txt
index 0c8bd368b..62a70df7f 100644
--- a/LICENSE.txt
+++ b/LICENSE.txt
@@ -43,6 +43,8 @@ Website content, text, images etc. (except as listed below):
Copyright (c) 2004 - 2015 I2P
See https://creativecommons.org/licenses/by-sa/4.0/
+ The I2P Proposal Process (i2p2www/spec/proposals/001-process.rst):
+ - 3-clause BSD, courtesy nickm / Tor
Flag icons (i2p2www/static/images/flags/):
- Jersey and EU flag icons: public domain, courtesy Xrmap flag
collection http://www.arvernes.com/wiki/index.php/Xrmap
diff --git a/i2p2www/spec/proposals/001-process.rst b/i2p2www/spec/proposals/001-process.rst
new file mode 100644
index 000000000..6fd6800b9
--- /dev/null
+++ b/i2p2www/spec/proposals/001-process.rst
@@ -0,0 +1,267 @@
+========================
+The I2P Proposal Process
+========================
+.. meta::
+ :author: str4d
+ :created: 2016-04-10
+ :thread: http://zzz.i2p/topics/1980
+ :lastupdated: 2016-04-10
+ :status: Draft
+
+.. contents::
+
+
+Overview
+========
+
+This document describes how to change the I2P specifications, how I2P proposals
+work, and the relationship between I2P proposals and the specifications.
+
+This document is adapted from the Tor proposal process [TORSPEC-PROCESS]_, and
+much of the content below was originally authored by Nick Mathewson.
+
+This is an informational document.
+
+
+Motivation
+==========
+
+Previously, our process for updating the I2P specifications was relatively
+informal: we'd make a proposal on the development forum and discuss the changes,
+then we would reach consensus and patch the specification with draft changes
+(not necessarily in that order), and finally we would implement the changes.
+
+This had a few problems.
+
+First, even at its most efficient, the old process would often have the
+spec out of sync with the code. The worst cases were those where
+implementation was deferred: the spec and code could stay out of sync for
+versions at a time.
+
+Second, it was hard to participate in discussion, since it was not always clear
+which portions of the discussion thread were part of the proposal, or which
+changes to the spec had been implemented. The development forums are also only
+accessible inside I2P, meaning that proposals could only be viewed by people who
+use I2P.
+
+Third, it was very easy to forget about some proposals because they would get
+buried several pages back in the forum thread list.
+
+
+How to change the specs now
+===========================
+
+First, somebody writes a proposal document. It should describe the change that
+should be made in detail, and give some idea of how to implement it. Once it's
+fleshed out enough, it becomes a proposal.
+
+Like an RFC, every proposal gets a number. Unlike RFCs, proposals can change
+over time and keep the same number, until they are finally accepted or rejected.
+The history for each proposal will be stored in the I2P website repository.
+
+Once a proposal is in the repository, we should discuss it on the corresponding
+thread and improve it until we've reached consensus that it's a good idea, and
+that it's detailed enough to implement. When this happens, we implement the
+proposal and incorporate it into the specifications. Thus, the specs remain the
+canonical documentation for the I2P protocol: no proposal is ever the canonical
+documentation for an implemented feature.
+
+(This process is pretty similar to the Python Enhancement Process, with the
+major exception that I2P proposals get re-integrated into the specs after
+implementation, whereas PEPs *become* the new spec.)
+
+
+Small changes
+-------------
+
+It's still okay to make small changes directly to the spec if the code can be
+written more or less immediately, or cosmetic changes if no code change is
+required. This document reflects the current developers' *intent*, not a
+permanent promise to always use this process in the future: we reserve the right
+to get really excited and run off and implement something in a
+caffeine-or-M&M-fueled all-night hacking session.
+
+
+How new proposals get added
+===========================
+
+To submit a proposal, post it on the development forum [DEV-FORUM-PROPOSAL]_ or
+enter a ticket with the proposal attached [TRAC-PROPOSAL]_.
+
+Once an idea has been proposed, a properly formatted (see below) draft exists,
+and rough consensus within the active development community exists that this
+idea warrants consideration, the proposal editors will officially add the
+proposal.
+
+The current proposal editors are zzz and str4d.
+
+
+What should go in a proposal
+============================
+
+Every proposal should have a header containing these fields::
+
+ :author:
+ :created:
+ :thread:
+ :lastupdated:
+ :status:
+
+- The ``thread`` field should be a link to the development forum thread where
+ this proposal was originally posted, or to a new thread created for discussing
+ this proposal.
+- The ``lastupdated`` field should initially be equal to the ``created`` field,
+ and should be updated whenever the proposal is changed.
+
+These fields should be set when necessary::
+
+ :supercedes:
+ :supercededby:
+
+- The ``supercedes`` field is a comma-separated list of all the proposals that
+ this proposal replaces. Those proposals should be Rejected and have their
+ ``supercededby`` field set to the number of this proposal.
+
+These fields are optional but recommended::
+
+ :target:
+ :implementedin:
+
+- The ``target`` field should describe which version the proposal is hoped to be
+ implemented in (if it's Open or Accepted).
+- The ``implementedin`` field should describe which version the proposal was
+ implemented in (if it's Finished or Closed).
+
+The body of the proposal should start with an Overview section explaining what
+the proposal's about, what it does, and about what state it's in.
+
+After the Overview, the proposal becomes more free-form. Depending on its
+length and complexity, the proposal can break into sections as appropriate, or
+follow a short discursive format. Every proposal should contain at least the
+following information before it is Accepted, though the information does not
+need to be in sections with these names.
+
+Motivation
+ What problem is the proposal trying to solve? Why does this problem matter?
+ If several approaches are possible, why take this one?
+
+Design
+ A high-level view of what the new or modified features are, how the new or
+ modified features work, how they interoperate with each other, and how they
+ interact with the rest of I2P. This is the main body of the proposal. Some
+ proposals will start out with only a Motivation and a Design, and wait for a
+ specification until the Design seems approximately right.
+
+Security implications
+ What effects the proposed changes might have on anonymity, how well
+ understood these effects are, and so on.
+
+Specification
+ A detailed description of what needs to be added to the I2P specifications
+ in order to implement the proposal. This should be in about as much detail
+ as the specifications will eventually contain: it should be possible for
+ independent programmers to write mutually compatible implementations of the
+ proposal based on its specifications.
+
+Compatibility
+ Will versions of I2P that follow the proposal be compatible with versions
+ that do not? If so, how will compatibility be achieved? Generally, we try
+ to not drop compatibility if at all possible; we haven't made a "flag day"
+ change since March 2008, and we don't want to do another one.
+
+Implementation
+ If the proposal will be tricky to implement in I2P's current architecture,
+ the document can contain some discussion of how to go about making it work.
+ Actual patches should go on public monotone branches, or be uploaded to
+ Trac.
+
+Performance and scalability notes
+ If the feature will have an effect on performance (in RAM, CPU, bandwidth)
+ or scalability, there should be some analysis on how significant this effect
+ will be, so that we can avoid really expensive performance regressions, and
+ so we can avoid wasting time on insignificant gains.
+
+References
+ If the proposal refers to outside documents, these should be listed.
+
+
+Proposal status
+===============
+
+Open
+ A proposal under discussion.
+
+Accepted
+ The proposal is complete, and we intend to implement it. After this point,
+ substantive changes to the proposal should be avoided, and regarded as a
+ sign of the process having failed somewhere.
+
+Finished
+ The proposal has been accepted and implemented. After this point, the
+ proposal should not be changed.
+
+Closed
+ The proposal has been accepted, implemented, and merged into the main
+ specification documents. The proposal should not be changed after this
+ point.
+
+Rejected
+ We're not going to implement the feature as described here, though we might
+ do some other version. See comments in the document for details. The
+ proposal should not be changed after this point; to bring up some other
+ version of the idea, write a new proposal.
+
+Draft
+ This isn't a complete proposal yet; there are definite missing pieces.
+ Please don't add any new proposals with this status; put them in the "ideas"
+ sub-directory instead.
+
+Needs-Revision
+ The idea for the proposal is a good one, but the proposal as it stands has
+ serious problems that keep it from being accepted. See comments in the
+ document for details.
+
+Dead
+ The proposal hasn't been touched in a long time, and it doesn't look like
+ anybody is going to complete it soon. It can become "Open" again if it gets
+ a new proponent.
+
+Needs-Research
+ There are research problems that need to be solved before it's clear whether
+ the proposal is a good idea.
+
+Meta
+ This is not a proposal, but a document about proposals.
+
+Reserve
+ This proposal is not something we're currently planning to implement, but we
+ might want to resurrect it some day if we decide to do something like what
+ it proposes.
+
+Informational
+ This proposal is the last word on what it's doing. It isn't going to turn
+ into a spec unless somebody copy-and-pastes it into a new spec for a new
+ subsystem.
+
+The editors maintain the correct status of proposals, based on rough consensus
+and their own discretion.
+
+
+Proposal numbering
+==================
+
+Numbers 000-099 are reserved for special and meta-proposals. 100 and up are
+used for actual proposals. Numbers aren't recycled.
+
+
+References
+==========
+
+.. [DEV-FORUM-PROPOSAL]
+ http://{{ i2pconv('zzz.i2p') }}/topics/new?forum_id=7-big-topics-ideas-proposals-and-discussion
+
+.. [TORSPEC-PROCESS]
+ https://gitweb.torproject.org/torspec.git/tree/proposals/001-process.txt
+
+.. [TRAC-PROPOSAL]
+ http://{{ i2pconv('trac.i2p2.i2p') }}/newticket?summary=New%20proposal:%20&type=enhancement&milestone=n/a&component=www/i2p&keywords=review-needed
--
GitLab