bsips/bsip-0001.md
2016-01-29 12:40:16 +01:00

206 lines
10 KiB
Markdown

BSIP: 0001
Title: BSIP Purpose and Guidelines
Authors: Fabian Schuh <Fabian@BitShares.eu>
Status: Draft
Type: Informational
Created: 2015-12-16
# What is a BSIP?
BSIP stands for BitShares Improvement Proposal but can also seen as an
improvement *protocol*. A BSIP is a design document providing information to the
BitShares community, or describing a new feature for BitShares or its processes
or environment. The BSIP should provide a concise technical specification of the
feature or the idea and a rationale for it. It may not only describe technical
improvements but also document *best-practises* and recommendations.
We intend BSIPs 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 BitShares. The BSIP author is responsible for building
consensus within the community and documenting dissenting opinions.
Because the BSIPs are maintained as text files in a versioned repository, their
revision history is the historical record of the feature proposal.
# BSIP Types
There are two kinds of BSIPs:
* An **Informational** BSIP describes a BitShares design issue, or provides general
guidelines or information to the BitShares community, but does not propose a
new feature, protocol change or any other modification. Informational BSIPs do
not necessarily represent a BitShares community consensus or recommendation,
so users and implementors are free to ignore Informational BSIPs or follow
their advice. Examples would be *best-practises* or *recommendations*.
* A **Protocol** Upgrade BSIP describes any change that affects most or all
BitShares implementations, such as a change to the protocol, a change in block
or transaction validity rules, or any change or addition that affects the
interoperability of applications using BitShares.
# Contributing
People wishing to submit BSIPs first should propose their idea as github
issue first. After discussion you will be assigned a number for the bsip
and can send a pull request for your *draft*. Once consensus among
discussion particpants is reached, the status can be switched to
*final*. From this time on, major changes of the document will not be
permitted.
If the proposal requires a protocol upgrade, the proposal is considered
*accepted* only if shareholders have approved a corresponding worker or
hard fork proposal. Informational BSIPs can only reach the *final*
state since their implementation is not enforced by the blockchain.
We are fairly liberal with listing BSIP drafts here since the
final decision of its actual implementation is made solely by BitShares
shareholders via approval voting.
It is highly recommended that a single BSIP contain a single key
proposal or new idea. Small enhancements or patches often don't need a
BSIP and can be injected into the BitShares development work flow with a
patch submission to the BitShares issue tracker. The more focused the
BSIP, the more successful it tends to be. The BSIP editor reserves the
right to reject BSIP proposals if they appear too unfocused or too
broad. If in doubt, split your BSIP into several well-focused ones.
Vetting an idea publicly before going as far as writing a BSIP is meant to save
the potential author time. Many ideas have been brought forward for changing
BitShares that have been rejected for various reasons. Asking the BitShares
community first if an idea is original helps prevent too much time being spent
on something that is guaranteed to be rejected based on prior discussions
(searching the internet does not always do the trick). It also helps to make
sure the idea is applicable to the entire community and not just the author.
Just because an idea sounds good to the author does not mean it will work for
most people in most areas where BitShares is used.
Following a discussion, the proposal should be sent to the BitShares developers
and the BSIP editors with the draft BSIP. This draft must be written in BSIP
style as described below, else it will be sent back without further regard until
proper formatting rules are followed.
If the BSIP editor approves, he will assign the BSIP a number, label it, give it
status "Draft", and add it to the git repository. The BSIP editor will not
unreasonably deny a BSIP. Reasons for denying BSIP status include duplication
of effort, being technically unsound, not providing proper motivation or
addressing backwards compatibility, or not in keeping with the BitShares
philosophy.
The BSIP author may update the Draft as necessary in the git repository. Updates
to drafts may also be submitted by the author as pull requests.
For a BSIP 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
solid and must not complicate the protocol unduly.
Once a BSIP has been published, the reference implementation must be
completed. When the reference implementation is complete and accepted
by the shareholders via approval voting, the status will be changed to
"Accepted". A BSIP can also be "Rejected" by shareholders.
Furthermore, a BSIP can be assigned status "Deferred". The BSIP author or editor
can assign the BSIP this status when no progress is being made on the BSIP. Once
a BSIP is deferred, the BSIP editor can re-assign it to draft status.
BSIPs can also be superseded by a different BSIP, rendering the original
obsolete. This is intended for Informational BSIPs, where version 2 of an API
can replace version 1.
# What belongs in a BSIP?
Each BSIP *should* have the following parts:
* Preamble -- RFC 822 style headers containing meta-data about the BSIP,
including the BSIP number, a short descriptive title (limited to a maximum of
44 characters), the names, and optionally the contact info for each author,
etc.
* Abstract -- a short (~200 word) description of the technical issue being
addressed.
* Copyright/public domain -- Each BSIP must either be explicitly labelled as
placed in the public domain (see this BSIP as an example) or licensed under
the Open Publication License.
* Motivation -- The motivation is critical for BSIPs that want to change the
BitShares protocol. It should clearly explain why the existing protocol
specification is inadequate to address the problem that the BSIP solves. BSIP
submissions without sufficient motivation may be rejected outright.
* Rationale -- The rationale fleshes out the specification by describing what
motivated the design and why particular design decisions were made. It should
describe alternate designs that were considered and related work, e.g. how the
feature is supported in other languages. The rationale should provide evidence
of consensus within the community and discuss important objections or concerns
raised during discussion.
* Specification -- The technical specification should describe the syntax and
semantics of any new feature. The specification should be detailed enough to
allow competing, interoperable implementations for any of the current
BitShares platforms.
* Discussion -- The BSIP shall include a discussion on positive and negative
effects on the BitShares ecosystem shall it be accepted by shareholders. This
section is supposed to be the most important section for shareholders to grasp
the full impact of the BSIP and help shareholders to make a decision.
* Summary for Shareholders -- Most BSIPs will probably be of technical nature.
However, many shareholders are not as technical as the author of a particular
BSIP. This non-technical paragraph serves as a place which can be used to
to interact with shareholders and help them form their opinion. It is not
meant to be a marketing driven paragraph to convince shareholders to vote
**for** or **against** a proposal, though.
# BSIP Formats and Templates
BSIPs should be written in mediawiki or markdown format. Image files should be
included in a subdirectory for that BSIP. A template including the header
preamble is provided in [this repository](BSIPs-Template.md).
# BSIP Editors
The current BSIP editors are:
* Fabian Schuh <Fabian@BitShares.eu>
* Sigve Kvalsvik <sigvekvalsvik@gmail.com>
* *cass* <Cass@BitShares.org>
The editors don't pass judgement on BSIPs. We merely do the administrative &
editorial part.
Many BSIPs are written and maintained by developers with write access to the
BitShares codebase. The BSIP editors monitor BSIP changes, and correct any
structure, grammar, spelling, or markup mistakes we see.
For each new BSIP that comes in an editor does the following:
* Read the BSIP to check if it is ready: sound and complete. The ideas must make
technical sense, even if they don't seem likely to be accepted.
* The title should accurately describe the content.
* Edit the BSIP for language (spelling, grammar, sentence structure, etc.),
markup (for reST BSIPs), code style (examples should match BSIP 8 & 7).
Once the BSIP is ready for the repository it should be submitted as a "pull
request" to the [https://github.com/BitShares/bsips BitShares/BSIPs] repository
on GitHub where it may get further feedback.
The BSIP editor will:
* Assign a BSIP number (almost always just the next available number, but
sometimes it's a special/joke number, like 666 or 3141) in the pull request
comments.
* Merge the pull request when the author is ready (allowing some time for
further peer review).
* List the BSIP in [[README.mediawiki]]
* Send email back to the BSIP author with next steps (post to BitShares mailing
list).
# History
This document was derived heavily from Python's PEP-0001 and Bitcoin BIP-0001.
In many places text was simply copied and modified. Although the
PEP-0001/BIP-0001 text was written by Barry Warsaw, Jeremy Hylton, and David
Goodger, they are not responsible for its use in the BitShares Improvement
Process, and should not be bothered with technical questions specific to
BitShares or the BSIP process. Please direct all comments to the BSIP editors
or the BitShares development mailing list.