From a908a8281d4bf7a788756813f3022de473f6881d Mon Sep 17 00:00:00 2001 From: Fabian Schuh Date: Wed, 16 Dec 2015 11:17:31 +0100 Subject: [PATCH] BSIP-0001 --- BSIPs-Template.md | 15 ++++ README.md | 16 +++- bsip-0001.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 BSIPs-Template.md create mode 100644 bsip-0001.md diff --git a/BSIPs-Template.md b/BSIPs-Template.md new file mode 100644 index 0000000..2a77292 --- /dev/null +++ b/BSIPs-Template.md @@ -0,0 +1,15 @@ + BSIP: + Title: + Authors: + Status: [ Draft | Accepted | Final | Withdrawn | Deferred | Rejected | Superseded] + Type: [ Informational | Protocol ] + Created: + Replaces: + Superseded-By: + Discussion: + +# Abstract +# Copyright +# Motivation +# Rational +# Specifications diff --git a/README.md b/README.md index 6bf28f5..029e718 100644 --- a/README.md +++ b/README.md @@ -1 +1,15 @@ -# bsips +# BitShares Improvement Protocol + +BSIP stands for BitShares Improvement Proposal. A BSIP is a design document +providing information to the BitShares community, or describing a new feature for +BitShares or its processes or environment. BSIPs provide a concise +technical specification of features and a rationale for them. + +The distinct document [BSIP Purpose and Guidelines](bsip-0001.md) gives a more +detailed explanation. + +# Available BSIPs + +Number | Title | Owner | Type | Status +------------------ | --------------------------- | -------------- | -------------- | ------- +[1](bsips-0001.md) | BSIP Purpose and Guidelines | Fabian Schuh | Informational | Draft diff --git a/bsip-0001.md b/bsip-0001.md new file mode 100644 index 0000000..c598de4 --- /dev/null +++ b/bsip-0001.md @@ -0,0 +1,192 @@ + BSIP: 0000 + Title: BSIP Purpose and Guidelines + Authors: Fabian Schuh + Status: Draft + Type: [ Informational | Protocol ] + Created: 2015-12-16 + +# What is a BSIP? + +BSIP stands for BitShares Improvement Proposal. 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 and a rationale for the feature. + +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. +* 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 issue or +document as pull request. After discussion it will be published here. 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. + +If the proposal requires a protocol upgrade, the proposal is considered *final* +only if shareholders have approved a corresponding worker proposal. + +The BSIP process begins with a new idea for BitShares. 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 accepted, 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 "Final". 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 (Satoshi, BitSharesJ, BitShares-js, libBitShares). + +* 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. + +# 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 + * Sigve Kvalsvik + * *cass* + +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. + +# Changelog