001-process.txt 8.2 KB

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