root / dotorg / v5 / html / beps / bep_0001.rst

BEP: 1
Title: The BitTorrent Enhancement Proposal Process 
Version: $Revision$
Last-Modified: $Date$
Author:  David Harrison <dave@bittorrent.com>
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 <editor@bittorrent.org>.  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 <editor@bittorrent.org> 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 <editor@bittorrent.org> or the BitTorrent mailing
list <bittorrent-list@bittorrent.org>.

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: