BEP:1
Title:The BitTorrent Enhancement Proposal Process
Version: b0977dde63ae00a101890ff6b16946f3bcdc5610
Last-Modified:Fri Nov 4 10:47:31 2016 -0700
Author: David Harrison <dave@bittorrent.com>
Status: Active
Type:Process
Created:10-Jan-2008
Post-History:4-Nov-2016 (ssiloti@bittorrent.com), updated to reflect the current github based workflow

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 reStructured text files in a versioned repository, their revision history is the historical record of the feature proposal [1].

BEP Types

There are three kinds of BEP:

  1. 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.
  2. 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.
  3. 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 editor is Steven Siloti <ssiloti@bittorrent.com>. 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 as an issue in the bittorrent.org github repository [1].

If the champion believes the idea warrants a BEP then the champion posts a pull request to github with 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, and gives it status "Draft". Once the pull request is updated accordingly, the editor will merge it. 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 open an issue in github seeking feedback and consensus 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 git commit permissions, or can post a pull request for the BEP editor to merge.

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 in a github issue or pull request will not be accepted. However, wherever possible, long open-ended discussions in github should be avoided. Strategies to keep the discussions efficient include: setting up a separate SIG forum 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:

bep_0001_1.png

Intellectual Property and BitTorrent Standards

Any idea submitted in a BEP will not be considered for standardization if the idea is not in the public domain. Before a BEP can be considered Final, all people (including the BEP authors) or entities with a claim on the intellectual property expressed in a BEP must assign in writing all intellectual property expressed in the BEP to the public domain. If the BEP authors lack the power to assign intellectual property rights then they must disclose this fact before the BEP can be considered Final.

Furthermore BEP authors should not knowingly propose anything in their BEPs that infringes on the intellectual property rights of others.

This policy statement should not be construed as meaning that BEP authors are required to assign software implementations of any particular idea to the public domain. BitTorrent implementors may retain all rights to their implementations.

History

This document was derived heavily from PEP-0001 [2]. 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 github repository.

Acknowledgements

Thanks to Barry Warsaw, David Goodger, and Guido van Rossum for their guidance.

References and Footnotes

[1](1, 2) bittorrent.org github repository (https://github.com/bittorrent/bittorrent.org)
[2]PEP-001: PEP Purposes and Guidelines, Warsaw, Hylton, Goodger. (http://www.python.org/dev/peps/pep-0001)