diff --git a/baip-0001.md b/baip-0001.md new file mode 100644 index 0000000..18dea7f --- /dev/null +++ b/baip-0001.md @@ -0,0 +1,213 @@ + BAIP: 0001 + Title: BAIP Purpose and Guidelines + Authors: Bangzi + Status: Draft + Type: Informational + Created: 2019-10-22 + +# What is a BAIP? + +BAIP stands for BitAssets Improvement Proposal but can also seen as an +improvement *consensus*. BitAssets are smartcoins technically owned by +the "committee-account" on the BitShares blockchain. A BAIP is a design document providing information to the BitShares community, +or describing a new feature for BitAssets or change its parameters or price feed +formula, logic and source. In short, this repository is for the community to discuss and organize votings for +things about bitCNY, bitUSD and etc. The BSIP repository will no longer be used for +this purpose unless there is a need to upgrade the BitShares protocol (aka hard fork). + +We intend BAIPs 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 BitAssets. The BAIP author is responsible for building +consensus within the community and documenting dissenting opinions. + +Because the BAIPs are maintained as text files in a versioned repository, their +revision history is the historical record of the feature proposal. + +# BAIP Types + +There are two kinds of BAIPs: + +* An **Informational** BAIP describes a BitAssets design issue, or provides general + guidelines or information to the BitShares community, but does not propose a + new feature, consensus change or any other modification. Informational BAIPs do + not necessarily represent a BitShares community consensus or recommendation, + so users and implementors are free to ignore Informational BAIPs or follow + their advice. Examples would be *best-practises* or *recommendations*. +* A **Consensus** Upgrade BAIP describes any change that affects some or all + BitAssets implementations, such as a parameters or price feed formula, logic and + source or addition that affects the applications using BitAssets. + +# Contributing + +People wishing to submit BAIPs first should propose their idea as github +issue first. After discussion you will be assigned a number for the BAIP +and can send a pull request for your *draft*. Once consensus among +discussion participants is reached, the status can be switched to +*accepted*. From this time on, major changes of the document will not be +permitted. + +If the proposal requires BTS holders approval, the proposal is considered +*implemented* only if BTS holders have approved a corresponding worker +proposal. Two poll worker proposals will be created standing FOR and AGAINST. +The proposal is considered approved by BTS holders when met these three criterias: +1. FOR worker get more voting power than AGAINST worker. +2. FOR worker get more voting power than BAIP-Threshold Worker. +3. Both No.1 & 2 above last for three consecutive days. + +Once a proposal approved by BTS Holders, new poll worker proposals are required to +supersede existing approved proposal. + +Informational BAIPs can only reach the *accepted* +state since their implementation is not enforced by the blockchain. + +We are fairly liberal with listing BAIP drafts here since the +final decision of its actual implementation is made solely by +BTS holders via approval voting. + +It is highly recommended that a single BAIP contain a single key +proposal or new idea. The more focused the +BAIP, the more successful it tends to be. The BAIP editor reserves the +right to reject BAIP proposals if they appear too unfocused or too +broad. If in doubt, split your BAIP into several well-focused ones. + +Vetting an idea publicly before going as far as writing a BAIP is meant to save +the potential author time. Many ideas have been brought forward for changing +BitAssets 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 BitAssets is used. + +Following a discussion, the proposal should be sent to the BitShares Committee +and the BAIP editors with the draft BAIP. This draft must be written in BAIP +style as described below, else it will be sent back without further regard until +proper formatting rules are followed. + +If the BAIP editor approves, he will assign the BAIP a number, label it, give it +status "Draft", and add it to the git repository. The BAIP editor will not +unreasonably deny a BAIP. Reasons for denying BAIP 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 BAIP 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 BAIP 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 consensus unduly. + +Once a BAIP has been published, the reference implementation must be +completed. When the reference implementation is complete and accepted +by the BTS holders via approval voting, the status will be changed to +"Accepted". A BAIP can also be "Rejected" by BTS holders. + +Furthermore, a BAIP can be assigned status "Deferred". The BAIP author or editor +can assign the BAIP this status when no progress is being made on the BAIP. Once +a BAIP is deferred, the BAIP editor can re-assign it to draft status. + +BAIPs can also be superseded by a different BAIP, rendering the original +obsolete. This is intended for Informational BAIPs, where version 2 of an API +can replace version 1. + +# What belongs in a BAIP? + +Each BAIP *should* have the following parts: + +* Preamble -- RFC 822 style headers containing meta-data about the BAIP, + including the BAIP 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 BAIP must either be explicitly labelled as + placed in the public domain (see this BAIP as an example) or licensed under + the Open Publication License. + +* Motivation -- The motivation is critical for BAIPs that want to change the + BitAssets. It should clearly explain why the existing consensus + specification is inadequate to address the problem that the BAIP solves. BAIP + 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 BAIP shall include a discussion on positive and negative + effects on the BitShares ecosystem shall it be accepted by BTS holders. This + section is supposed to be the most important section for BTS holders to grasp + the full impact of the BAIP and help BTS holders to make a decision. + +* Summary for BTS holders -- Most BAIPs will probably be of technical nature. + However, many BTS holders are not as technical as the author of a particular + BAIP. This non-technical paragraph serves as a place which can be used to + to interact with BTS holders and help them form their opinion. It is not + meant to be a marketing driven paragraph to convince BTS holders to vote + **for** or **against** a proposal, though. + +# BAIP Formats and Templates + +BAIPs should be written in mediawiki or markdown format. Image files should be +included in a subdirectory for that BAIP. A template including the header +preamble is provided in [this repository](BAIPs-Template.md). + +# BAIP Editors + +The current BAIP editors are: + + * Abit More + * Jerry Liu + * Fabian Schuh + +The editors don't pass judgement on BAIPs. We merely do the administrative & +editorial part. + +Many BAIPs are written and maintained by Committee with write access to the +BitShares codebase. The BAIP editors monitor BAIP changes, and correct any +structure, grammar, spelling, or markup mistakes we see. + +For each new BAIP that comes in an editor does the following: + +* Read the BAIP 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 BAIP for language (spelling, grammar, sentence structure, etc.), + markup (for reST BAIPs), code style (examples should match BAIP 8 & 7). + +Once the BAIP is ready for the repository it should be submitted as a "pull +request" to the [https://github.com/BitShares/baips] repository +on GitHub where it may get further feedback. + +The BAIP editor will: + +* Assign a BAIP 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 BAIP in [[README.mediawiki]] +* Send email back to the BAIP author with next steps (post to BitShares mailing + list). + +# History + +This document was derived heavily from Bitshares BSIP-0001, Python's PEP-0001 and Bitcoin BIP-0001. +In many places text was simply copied and modified. Although the +BSIP-0001/PEP-0001/BIP-0001 text was written by Fabian Schuh, Barry Warsaw, Jeremy Hylton, and David +Goodger, they are not responsible for its use in the BitAsset Improvement +Process, and should not be bothered with technical questions specific to +BitShares or the BAIP process. Please direct all comments to the BAIP editors +or the BitShares development mailing list.