diff options
Diffstat (limited to 'doc/spec/proposals/001-process.txt')
| -rw-r--r-- | doc/spec/proposals/001-process.txt | 184 |
1 files changed, 0 insertions, 184 deletions
diff --git a/doc/spec/proposals/001-process.txt b/doc/spec/proposals/001-process.txt deleted file mode 100644 index e2fe358fe..000000000 --- a/doc/spec/proposals/001-process.txt +++ /dev/null @@ -1,184 +0,0 @@ -Filename: 001-process.txt -Title: The Tor Proposal Process -Author: Nick Mathewson -Created: 30-Jan-2007 -Status: Meta - -Overview: - - This document describes how to change the Tor specifications, how Tor - proposals work, and the relationship between Tor proposals and the - specifications. - - This is an informational document. - -Motivation: - - Previously, our process for updating the Tor specifications was maximally - informal: we'd patch the specification (sometimes forking first, and - sometimes not), then discuss the patches, reach consensus, and implement - the changes. - - This had a few problems. - - First, even at its most efficient, the old process would often have the - spec out of sync with the code. The worst cases were those where - implementation was deferred: the spec and code could stay out of sync for - versions at a time. - - Second, it was hard to participate in discussion, since you had to know - which portions of the spec were a proposal, and which were already - implemented. - - Third, it littered the specifications with too many inline comments. - [This was a real problem -NM] - [Especially when it went to multiple levels! -NM] - [XXXX especially when they weren't signed and talked about that - thing that you can't remember after a year] - -How to change the specs now: - - First, somebody writes a proposal document. It should describe the change - that should be made in detail, and give some idea of how to implement it. - Once it's fleshed out enough, it becomes a proposal. - - Like an RFC, every proposal gets a number. Unlike RFCs, proposals can - change over time and keep the same number, until they are finally - accepted or rejected. The history for each proposal - will be stored in the Tor repository. - - Once a proposal is in the repository, we should discuss and improve it - until we've reached consensus that it's a good idea, and that it's - detailed enough to implement. When this happens, we implement the - proposal and incorporate it into the specifications. Thus, the specs - remain the canonical documentation for the Tor protocol: no proposal is - ever the canonical documentation for an implemented feature. - - (This process is pretty similar to the Python Enhancement Process, with - the major exception that Tor proposals get re-integrated into the specs - after implementation, whereas PEPs _become_ the new spec.) - - {It's still okay to make small changes directly to the spec if the code - can be - written more or less immediately, or cosmetic changes if no code change is - required. This document reflects the current developers' _intent_, not - a permanent promise to always use this process in the future: we reserve - the right to get really excited and run off and implement something in a - caffeine-or-m&m-fueled all-night hacking session.} - -How new proposals get added: - - Once an idea has been proposed on the development list, a properly formatted - (see below) draft exists, and rough consensus within the active development - community exists that this idea warrants consideration, the proposal editor - will officially add the proposal. - - To get your proposal in, send it to or-dev. - - The current proposal editor is Nick Mathewson. - -What should go in a proposal: - - Every proposal should have a header containing these fields: - Filename, Title, Author, Created, Status. - - These fields are optional but recommended: - Target, Implemented-In. - The Target field should describe which version the proposal is hoped to be - implemented in (if it's Open or Accepted). The Implemented-In field - should describe which version the proposal was implemented in (if it's - Finished or Closed). - - 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 on its - 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 is "ACCEPTED", - though 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 the proposed changes might 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 - be achieved? Generally, we try to not drop compatibility if at - all possible; we haven't made a "flag day" change since May 2004, - and we don't want to do another one. - - 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. Actual patches should go on public git - branches, or be uploaded to trac. - - 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. - -Proposal status: - - Open: A proposal under discussion. - - Accepted: The proposal is complete, and we intend to implement it. - After this point, substantive changes to the proposal should be - avoided, and regarded as a sign of the process having failed - somewhere. - - Finished: The proposal has been accepted and implemented. After this - point, the proposal should not be changed. - - Closed: The proposal has been accepted, implemented, and merged into the - main specification documents. The proposal should not be changed after - this point. - - Rejected: We're not going to implement the feature as described here, - though we might do some other version. See comments in the document - for details. The proposal should not be changed after this point; - to bring up some other version of the idea, write a new proposal. - - Draft: This isn't a complete proposal yet; there are definite missing - pieces. Please don't add any new proposals with this status; put them - in the "ideas" sub-directory instead. - - Needs-Revision: The idea for the proposal is a good one, but the proposal - as it stands has serious problems that keep it from being accepted. - 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. 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. - - Meta: This is not a proposal, but a document about proposals. - - - The editor maintains the correct status of proposals, based on rough - consensus and his own discretion. - -Proposal numbering: - - Numbers 000-099 are reserved for special and meta-proposals. 100 and up - are used for actual proposals. Numbers aren't recycled. |