1 Filename: 001-process.txt
2 Title: The Tor Proposal Process
11 This document describes how to change the Tor specifications, how Tor
12 proposals work, and the relationship between Tor proposals and the
15 This is an informational document.
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
24 This had a few problems.
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
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
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]
41 How to change the specs now:
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.
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.
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.
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.)
63 {It's still okay to make small changes directly to the spec if the code
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.}
71 How new proposals get added:
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.
78 To get your proposal in, send it to or-dev.
80 The current proposal editor is Nick Mathewson.
82 What should go in a proposal:
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
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
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.
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.
105 Motivation: What problem is the proposal trying to solve? Why does
106 this problem matter? If several approaches are possible, why take this
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.
116 Security implications: What effects the proposed changes might have on
117 anonymity, how well understood these effects are, and so on.
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
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.
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.
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.
144 Open: A proposal under discussion.
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
151 Finished: The proposal has been accepted and implemented. After this
152 point, the proposal should not be changed.
154 Closed: The proposal has been accepted, implemented, and merged into the
155 main specification documents. The proposal should not be changed after
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.
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.
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.
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.
175 Needs-Research: There are research problems that need to be solved before
176 it's clear whether the proposal is a good idea.
178 Meta: This is not a proposal, but a document about proposals.
181 The editor maintains the correct status of proposals, based on rough
182 consensus and his own discretion.
186 Numbers 000-099 are reserved for special and meta-proposals. 100 and up
187 are used for actual proposals. Numbers aren't recycled.