BEP: 1 Title: The BitTorrent Enhancement Proposal Process Version: $Revision$ Last-Modified: $Date$ Author: David Harrison Status: Active Draft Type: Process Created: 10-Jan-2008 Post-History: What is a BEP ============= BEP stands for BitTorrent Enhancement Proposal. A BEP is a design document providing information to the BitTorrent community, or describing a new feature for the BitTorrent protocols. The BEP should provide a concise technical specification of the feature and a rationale for the feature. We intend BEPs to be the primary mechanisms for proposing new features, for collecting community input on an issue, and for documenting the design decisions that have gone into BitTorrent. The BEP author is responsible for building consensus within the community and documenting dissenting opinions. Because the BEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal [#svn]_. BEP Types ========= There are three kinds of BEP: #. A Standards Track BEP describes an extension to one of the BitTorrent protocols or a change in the behavior of one of the actors in these protocols, where the actors are currently clients, trackers, and web servers. #. An Informational BEP describes a BitTorrent design issue, or provides general guidelines or information to the BitTorrent community, but does not propose an extension. Informational BEPs do not necessarily represent a BitTorrent community consensus or recommendation, so users and implementors are free to ignore Informational BEPs or follow their advice. #. A Process BEP describes a process surrounding BitTorrent, or proposes a change to (or an event in) a process. Process BEPs are like Standards Track BEPs but apply to areas other than the BitTorrent protocols. They are more than recommendations, and users are typically not free to ignore them. Examples include release schedules, procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in BitTorrent development. BEP Work FLow ============= The BEP editors assign BEP numbers and change their status. The current BEP editors are David Harrison and Arvid Norberg. Please send all BEP-related email to . Also see BEP Editor Responsibilities & Workflow below. The BEP process begins with a new idea for the BitTorrent protocols. It is highly recommended that a single BEP contain a single key proposal. The BEP editor reserves the right to reject BEP proposals if they appear unfocussed or overly broad. If in doubt, split your BEP into muliple BEPs. Each BEP must have a champion -- someone who writes the BEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The BEP champion should first post a description of the idea to the bitorrent-list@bittorrent.org. If the champion believes the idea warrants a BEP then the champion emails the BEP editor with a proposed title and a draft of the BEP. This draft must be written in BEP style as described below. If the BEP editor approves, he assigns the BEP a number, labels it as Standards Track, Informational, or Process, gives it status "Draft", and creates and checks-in the initial draft of the BEP to the subversion repository. The BEP editor will not unreasonably deny a BEP. Reasons for denying BEP status include duplication of effort, being technically unsound, not providing proper motivation or not addressing backwards compatibility. The BDFL (Benevolent Dictator for Life, Bram Cohen) can be consulted during the approval phase, and is the final arbiter of the draft's BEP-ability. If a pre-BEP is rejected, the author may elect to take the pre-BEP to the bittorrent-list@bittorrent.org mailing list seeking feedback and consesnsus from the community at large. A proposal may be re-submitted after it has been revised. The champion is then responsible for marshaling community support for it. As updates are necessary, the BEP author can check in new versions if they have SVN commit permissions, or can email new BEP versions to the BEP editor for committing. Standards Track BEPs consist of two parts, a design document and a reference implementation. The reference implementation need not be complete when a BEP is submitted to the editors. However Standards Track BEPs must include an implementation in at least one BitTorrent client with publicy available code before it can be considered Final. BEP champions are responsible for collecting community feedback on a BEP before submitting it for review. A BEP that has not been discussed on bittorrent-list@bittorrent.org will not be accepted. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep the discussions efficient include: setting up a separate SIG mailing list for the topic, having the BEP author accept private comments in the early design phases, setting up a wiki page, etc. BEP authors should use their discretion here. Once the authors have completed a BEP, they must inform the BEP editor that it is ready for review. BEPs are reviewed by the BDFL and his chosen consultants, who may accept or reject a BEP or send it back to the author(s) for revision. For a BEP that is pre-determined to be acceptable (e.g., it is an obvious win as-is and/or its implementation already exists in one or more popular BitTorrent clients) the BDFL may also initiate a BEP review, first notifying the BEP author(s) and giving them a chance to make revisions. For a BEP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be functional and have been tested in live BitTorrent swarms. Supporting results from analyses, testbed experiments and event-based simulations are also recommended where appropriate. A Standards Track document should include the rationale behind a proposal and may briefly summarize analytical, simulation, or experimental results where necessary to illustrate or motivate the enhancement. However, detailed analytical, simulation, and experiment results, especially comparing different approaches to the same problem should be omitted from Standards Track BEPs and instead cited from a published paper or a separate Informational BEP. Once a BEP has been accepted, the reference implementation must be completed. When the reference implementation is complete and accepted by the BDFL, the status will be changed to "Final". A BEP can also be assigned status "Deferred". The BEP author or editor can assign the BEP this status when no progress is being made on the BEP. Once a BEP is deferred, the BEP editor can re-assign it to draft status. A BEP can also be "Rejected". Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. BEPs can also be replaced by a different BEP, rendering the original obsolete. This is intended for Informational BEPs, where version 2 of an API can replace version 1. The possible paths of the status of BEPs are as follows: .. image :: bep_0001_1.png History ======= This document was derived heavily from PEP-0001 [#PEP-1]_. In many places text was simply copied and modified. Although the PEP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David Goodger, they are not responsible for its use in the BitTorent Enhancement Process, and should not be bothered with technical questions specific to BitTorrent or the BEP process. Please direct all comments to the BitTorrent editors or the BitTorrent mailing list . Acknowledgements ================ Thanks to Barry Warsaw, David Goodger, and Guido van Rossum for their guidance. References and Footnotes ======================== .. [#svn] This historical record is available by the normal SVN commands for retrieving older revisions. For those without direct access to the SVN tree, you can browse the current and past BEP revisions here: http://svn.bittorrent.org/beps/trunk/ .. [#PEP-1] PEP-001: PEP Purposes and Guidelines, Warsaw, Hylton, Goodger. (http://www.python.org/dev/peps/pep-0001) .. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 coding: utf-8 End: