doc/spec/proposals/001-process.txt

   1 Filename: 001-process.txt
   2 Title: The Tor Proposal Process
   3 Version: $Revision$
   4 Last-Modified: $Date$
   5 Author: Nick Mathewson
   6 Created: 30-Jan-2007
   7 Status: Meta
   8
   9 Overview:
  10
  11    This document describes how to change the Tor specifications, how Tor
  12    proposals work, and the relationship between Tor proposals and the
  13    specifications.
  14
  15    This is an informational document.
  16
  17 Motivation:
  18
  19    Previously, our process for updating the Tor specifications was maximally
  20    informal: we'd patch the specification (sometimes forking first, and
  21    sometimes not), then discuss the patches, reach consensus, and implement
  22    the changes.
  23
  24    This had a few problems.
  25
  26    First, even at its most efficient, the old process would often have the
  27    spec out of sync with the code.  The worst cases were those where
  28    implementation was deferred: the spec and code could stay out of sync for
  29    versions at a time.
  30
  31    Second, it was hard to participate in discussion, since you had to know
  32    which portions of the spec were a proposal, and which were already
  33    implemented.
  34
  35    Third, it littered the specifications with too many inline comments.
  36      [This was a real problem -NM]
  37        [Especially when it went to multiple levels! -NM]
  38          [XXXX especially when they weren't signed and talked about that
  39           thing that you can't remember after a year]
  40
  41 How to change the specs now:
  42
  43    First, somebody writes a proposal document.  It should describe the change
  44    that should be made in detail, and give some idea of how to implement it.
  45    Once it's fleshed out enough, it becomes a proposal.
  46
  47    Like an RFC, every proposal gets a number.  Unlike RFCs, proposals can
  48    change over time and keep the same number, until they are finally
  49    accepted or rejected.  The history for each proposal
  50    will be stored in the Tor Subversion repository.
  51
  52    Once a proposal is in the repository, we should discuss and improve it
  53    until we've reached consensus that it's a good idea, and that it's
  54    detailed enough to implement.  When this happens, we implement the
  55    proposal and incorporate it into the specifications.  Thus, the specs
  56    remain the canonical documentation for the Tor protocol: no proposal is
  57    ever the canonical documentation for an implemented feature.
  58
  59    (This process is pretty similar to the Python Enhancement Process, with
  60    the major exception that Tor proposals get re-integrated into the specs
  61    after implementation, whereas PEPs _become_ the new spec.)
  62
  63    {It's still okay to make small changes directly to the spec if the code
  64    can be
  65    written more or less immediately, or cosmetic changes if no code change is
  66    required.  This document reflects the current developers' _intent_, not
  67    a permanent promise to always use this process in the future: we reserve
  68    the right to get really excited and run off and implement something in a
  69    caffeine-or-m&m-fueled all-night hacking session.}
  70
  71 How new proposals get added:
  72
  73   Once an idea has been proposed on the development list, a properly formatted
  74   (see below) draft exists, and rough consensus within the active development
  75   community exists that this idea warrants consideration, the proposal editor
  76   will officially add the proposal.
  77
  78   To get your proposal in, send it to or-dev.
  79
  80   The current proposal editor is Nick Mathewson.
  81
  82 What should go in a proposal:
  83
  84    Every proposal should have a header containing these fields:
  85      Filename, Title, Version, Last-Modified, Author, Created, Status.
  86    The Version and Last-Modified fields should use the SVN Revision and Date
  87    tags respectively.
  88
  89    These fields are optional but recommended:
  90      Target, Implemented-In.
  91    The Target field should describe which version the proposal is hoped to be
  92    implemented in (if it's Open or Accepted).  The Implemented-In field
  93    should describe which version the proposal was implemented in (if it's
  94    Finished or Closed).
  95
  96    The body of the proposal should start with an Overview section explaining
  97    what the proposal's about, what it does, and about what state it's in.
  98
  99    After the Overview, the proposal becomes more free-form.  Depending on its
 100    the length and complexity, the proposal can break into sections as
 101    appropriate, or follow a short discursive format.  Every proposal should
 102    contain at least the following information before it is "ACCEPTED",
 103    though the information does not need to be in sections with these names.
 104
 105       Motivation: What problem is the proposal trying to solve?  Why does
 106         this problem matter?  If several approaches are possible, why take this
 107         one?
 108
 109       Design: A high-level view of what the new or modified features are, how
 110         the new or modified features work, how they interoperate with each
 111         other, and how they interact with the rest of Tor.  This is the main
 112         body of the proposal.  Some proposals will start out with only a
 113         Motivation and a Design, and wait for a specification until the
 114         Design seems approximately right.
 115
 116       Security implications: What effects the proposed changes might have on
 117         anonymity, how well understood these effects are, and so on.
 118
 119       Specification: A detailed description of what needs to be added to the
 120         Tor specifications in order to implement the proposal.  This should
 121         be in about as much detail as the specifications will eventually
 122         contain: it should be possible for independent programmers to write
 123         mutually compatible implementations of the proposal based on its
 124         specifications.
 125
 126       Compatibility: Will versions of Tor that follow the proposal be
 127         compatible with versions that do not?  If so, how will compatibility
 128         be achieved?  Generally, we try to not drop compatibility if at
 129         all possible; we haven't made a "flag day" change since May 2004,
 130         and we don't want to do another one.
 131
 132       Implementation: If the proposal will be tricky to implement in Tor's
 133         current architecture, the document can contain some discussion of how
 134         to go about making it work.
 135
 136       Performance and scalability notes: If the feature will have an effect
 137         on performance (in RAM, CPU, bandwidth) or scalability, there should
 138         be some analysis on how significant this effect will be, so that we
 139         can avoid really expensive performance regressions, and so we can
 140         avoid wasting time on insignificant gains.
 141
 142 Proposal status:
 143
 144    Open: A proposal under discussion.
 145
 146    Accepted: The proposal is complete, and we intend to implement it.
 147       After this point, substantive changes to the proposal should be
 148       avoided, and regarded as a sign of the process having failed
 149       somewhere.
 150
 151    Finished: The proposal has been accepted and implemented.  After this
 152       point, the proposal should not be changed.
 153
 154    Closed: The proposal has been accepted, implemented, and merged into the
 155       main specification documents.  The proposal should not be changed after
 156       this point.
 157
 158    Rejected: We're not going to implement the feature as described here,
 159       though we might do some other version.  See comments in the document
 160       for details.  The proposal should not be changed after this point;
 161       to bring up some other version of the idea, write a new proposal.
 162
 163    Draft: This isn't a complete proposal yet; there are definite missing
 164       pieces.  Please don't add any new proposals with this status; put them
 165       in the "ideas" sub-directory instead.
 166
 167    Needs-Revision: The idea for the proposal is a good one, but the proposal
 168       as it stands has serious problems that keep it from being accepted.
 169       See comments in the document for details.
 170
 171    Dead: The proposal hasn't been touched in a long time, and it doesn't look
 172       like anybody is going to complete it soon.  It can become "Open" again
 173       if it gets a new proponent.
 174
 175    Needs-Research: There are research problems that need to be solved before
 176       it's clear whether the proposal is a good idea.
 177
 178    Meta: This is not a proposal, but a document about proposals.
 179
 180
 181    The editor maintains the correct status of proposals, based on rough
 182    consensus and his own discretion.
 183
 184 Proposal numbering:
 185
 186    Numbers 000-099 are reserved for special and meta-proposals.  100 and up
 187    are used for actual proposals.  Numbers aren't recycled.