From df341d848887401673e97108c8a304bc219c4e95 Mon Sep 17 00:00:00 2001 From: bangzi1001 <36911788+bangzi1001@users.noreply.github.com> Date: Tue, 22 Oct 2019 10:39:07 +0800 Subject: [PATCH 1/2] Create baip-0001.md : BAIP Purpose and Guidelines --- baip-0001.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 baip-0001.md diff --git a/baip-0001.md b/baip-0001.md new file mode 100644 index 0000000..fc48c01 --- /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 BitShares Committee's SmartCoins +including but not limited to BitCNY, BitUSD and BitBTC. 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. The BAIP 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 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. From 8636258c1dd460c6dd4ac5ec89e38244d16752ae Mon Sep 17 00:00:00 2001 From: bangzi1001 <36911788+bangzi1001@users.noreply.github.com> Date: Wed, 23 Oct 2019 07:55:56 +0800 Subject: [PATCH 2/2] Update baip-0001.md --- baip-0001.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/baip-0001.md b/baip-0001.md index fc48c01..18dea7f 100644 --- a/baip-0001.md +++ b/baip-0001.md @@ -8,12 +8,12 @@ # What is a BAIP? BAIP stands for BitAssets Improvement Proposal but can also seen as an -improvement *consensus*. BitAssets are BitShares Committee's SmartCoins -including but not limited to BitCNY, BitUSD and BitBTC. 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. The BAIP 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. +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