[or-cvs] r9543: Mark 100 dead; write more about what should go in a proposal (in tor/trunk: . doc/spec/proposals)

[nickm at seul.org]

Author: nickm
Date: 2007-02-09 22:43:00 -0500 (Fri, 09 Feb 2007)
New Revision: 9543

Modified:
   tor/trunk/
   tor/trunk/doc/spec/proposals/000-index.txt
   tor/trunk/doc/spec/proposals/001-process.txt
   tor/trunk/doc/spec/proposals/100-tor-spec-udp.txt
Log:
 r12202 at Kushana:  nickm | 2007-02-09 12:05:53 -0500
 Mark 100 dead; write more about what should go in a proposal; add status tags to index.



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r12202] on c95137ef-5f19-0410-b913-86e773d04f59

Modified: tor/trunk/doc/spec/proposals/000-index.txt
===================================================================
--- tor/trunk/doc/spec/proposals/000-index.txt	2007-02-09 07:09:26 UTC (rev 9542)
+++ tor/trunk/doc/spec/proposals/000-index.txt	2007-02-10 03:43:00 UTC (rev 9543)
@@ -14,14 +14,14 @@
 
 Proposals by number:
 
-000  Index of Tor Proposals
-001  The Tor Proposal Process
-098  Proposals that should be written
-099  Miscellaneous proposals
-100  Tor Unreliable Datagram Extension Proposal
-101  Voting on the Tor Directory System.
-102  Droping "opt" from the directory format
-103  Splitting identity key from regularly used signing key.
-104  Long and Short Router Descriptors
-105  Version negotiation for the Tor protocol
+000  Index of Tor Proposals [META]
+001  The Tor Proposal Process [META]
+098  Proposals that should be written [META]
+099  Miscellaneous proposals [META]
+100  Tor Unreliable Datagram Extension Proposal [DEAD]
+101  Voting on the Tor Directory System [OPEN]
+102  Droping "opt" from the directory format [CLOSED]
+103  Splitting identity key from regularly used signing key [OPEN]
+104  Long and Short Router Descriptors [OPEN]
+105  Version negotiation for the Tor protocol [OPEN]
 

Modified: tor/trunk/doc/spec/proposals/001-process.txt
===================================================================
--- tor/trunk/doc/spec/proposals/001-process.txt	2007-02-09 07:09:26 UTC (rev 9542)
+++ tor/trunk/doc/spec/proposals/001-process.txt	2007-02-10 03:43:00 UTC (rev 9543)
@@ -82,7 +82,8 @@
       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.
+      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.
@@ -96,7 +97,54 @@
 
 What should go in a proposal:
 
-   WRITE MORE.
+   Every proposal should have a header containing these fields:
+     Filename, Title, Version, Last-Modified, Author, Created, Status.
+   The Version and Last-Modified fields should use the SVN Revision and Date
+   tags respectively.
 
-   Before a proposal is "ACCEPTED", it should have about as much detail as
-   the specs would for the proposed feature.
+   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 its
+   the 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 can be "ACCEPTED",
+   thought 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 Tor.  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 might the proposed changes have on
+        anonymity, how well understood these effects are, and so on.
+
+      Specification: A detailed description of what needs to be added to the
+        Tor 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 Tor that follow the proposal be
+        compatible with versions that do not?  If so, how will compatibility
+        me achieved?  Generally, we try to not to drop compatibility if at
+        all possible; we haven't made a "flag day" change since 2003 or
+        earlier, and we don't want to do another one.  [XXX is this true?]
+
+      Implementation: If the proposal will be tricky to implement in Tor's
+        current architecture, the document can contain some discussion of how
+        to go about making it work.
+
+      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.
+

Modified: tor/trunk/doc/spec/proposals/100-tor-spec-udp.txt
===================================================================
--- tor/trunk/doc/spec/proposals/100-tor-spec-udp.txt	2007-02-09 07:09:26 UTC (rev 9542)
+++ tor/trunk/doc/spec/proposals/100-tor-spec-udp.txt	2007-02-10 03:43:00 UTC (rev 9543)
@@ -4,7 +4,7 @@
 Last-Modified: $Date$
 Author: Marc Liberatore
 Created:
-Status: Needs-Revision
+Status: Dead
 
 Overview: