proposals/001-process.txt

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