diff --git a/README.mediawiki b/README.mediawiki index e89ccf5b..260a740d 100644 --- a/README.mediawiki +++ b/README.mediawiki @@ -28,6 +28,13 @@ Those proposing changes should consider that ultimately consent may rest with th | Process | Active |- +| [[bip-0003.md|3]] +| +| Updated BIP Process +| Murch +| Process +| Draft +|- | [[bip-0008.mediawiki|8]] | | Version bits with lock-in by height diff --git a/bip-0003.md b/bip-0003.md new file mode 100644 index 00000000..c7d46871 --- /dev/null +++ b/bip-0003.md @@ -0,0 +1,753 @@ +``` + BIP: 3 + Title: Updated BIP Process + Author: Murch + Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0003 + Status: Draft + Type: Process + Created: 2025-01-09 + License: BSD-2-Clause + Post-History: https://github.com/murchandamus/bips/pull/2 + https://gnusha.org/pi/bitcoindev/59fa94cea6f70e02b1ce0da07ae230670730171c.camel@timruffing.de/#t + Requires: 123 + Replaces: 2 +``` + +## Abstract + +This _Bitcoin Improvement Proposal (BIP)_ provides information about the preparation of BIPs and policies relating to +the publication of BIPs. It replaces [BIP 2](bip-0002.mediawiki) with a streamlined process, and may be amended to +address the evolving needs of the BIP process. + +## Motivation + +BIP 2 was written in 2016. +This BIP revisits aspects of the BIP 2 process +that did not achieve broad adoption, reduces the judgment calls assigned to the BIP Editor role, delineates the +BIP Types more clearly, and generalizes the BIP process to meet the community’s use of the repository. + +## Fundamentals + +### What is a BIP? + +BIPs cover the range of interests of the Bitcoin[^capitalization] community. The main topic is information and technologies that support and expand the utility of the bitcoin +currency. Most BIPs provide a concise, self-contained, technical description of one new concept, feature, or standard. +Some BIPs describe processes, implementation guidelines, best practices, incident reports (e.g., +[BIP 50](bip-0050.mediawiki)), or other information relevant to the Bitcoin community. However, any topics related to +the Bitcoin protocol, peer-to-peer network, and client software may be acceptable. + +BIPs are intended to be a means for proposing new protocol features, coordinating client standards, and +documenting design decisions that have gone into implementations. BIPs may be submitted by anyone. + +The scope of the BIP +repository is limited to BIPs that do not oppose the fundamental principle that Bitcoin constitutes a peer-to-peer +electronic cash system for the bitcoin currency. + +### BIP Ownership + +Each BIP is primarily owned by its authors and represents the authors’ opinion or recommendation. The authors are +expected to foster discussion, address feedback and dissenting opinions, and, if applicable, advance the adoption of +their proposal within the Bitcoin community. As a BIP progresses through the workflow, it becomes increasingly + co-owned by the Bitcoin community. + +#### Authors and Deputies + +Authors may want additional help with the BIP process after writing an initial draft. In that case, they may assign +one or more Deputies to their BIP. Deputies are stand-in owners of a BIP who were not involved in writing the +document. They support the authors in advancing the proposal, or act as a point of contact for the BIP in the absence of the +authors. Deputies may perform the role of Authors for any aspect of the BIP process unless overruled by an Author. +Deputies share ownership of the BIP at the discretion of the Authors. + +### What is the Significance of BIPs? + +BIPs do not define what Bitcoin is: individual BIPs do not represent Bitcoin community consensus or a general +recommendation for implementation. A BIP represents a personal recommendation by the BIP authors to the Bitcoin +community. Some BIPs may never be adopted. Some BIPs may be adopted by one or more Bitcoin clients or other related +software. Some may even end up changing the consensus rules that the Bitcoin ecosystem jointly enforces. + +### What is the Purpose of the BIPs Repository? + +The [BIPs repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals. +Through its high visibility, it facilitates the community-wide consideration of BIPs and provides a well-established +source to retrieve the latest version of any BIP. The repository transparently records all changes to each BIP and +allows any community member to retain a complete copy of the archive easily. + +The BIPs repository is not a tool to track acceptance[^acceptance], adoption, or community consensus on BIPs, beyond +providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience. +There is no formal or informal decision body that governs Bitcoin development or decides acceptance of BIPs. Bitcoin +development emerges from the participation of shareholders across the ecosystem. + +## BIP Format and Structure + +### Specification + +Authors may choose to submit BIPs in MediaWiki or Markdown[^markdown] format. + +Each BIP must have a _Preamble_, an _Abstract_, a _Copyright_, and a _Motivation_ section. Authors should consider all issues in the +following list and address each as appropriate. + +* Preamble — Headers containing metadata about the BIP (see the section [BIP Header Preamble](#bip-header-preamble) + below). +* Abstract — A short description of the issue being addressed. +* Motivation — Why is this BIP being written? Clearly explain how the existing situation presents a problem and why the proposed idea resolves the + issue or improves upon the current situation. +* Specification — The technical specification should describe the syntax and semantics of any new feature. The + specification should be detailed enough to enable any Bitcoin project to create an interoperable implementation. +* Rationale — The rationale fleshes out the specification by describing what inspired the design and why particular + design decisions were made. It should describe related work and alternate designs that were considered. The rationale + should record relevant objections or important concerns that were raised and addressed as this proposal was developed. +* Backward Compatibility — Any BIP that introduces incompatibilities must include a section describing these incompatibities and their severity as well as provide instructions on how + implementers and users should deal with these incompatibilities. +* Reference Implementation — Where applicable, a reference implementation, test vectors, and documentation must be + finished before the BIP can be given the status "Complete". Test vectors must be provided in the BIP or + as auxiliary files (see [Auxiliary Files](#auxiliary-files)) under an acceptable license. The reference implementation can be provided in the BIP, as an auxiliary file, or per reference to a pull request that is expected to remain available permanently. +* Changelog — A section to track modifications to a BIP after reaching Complete status. +* Copyright — The BIP must be placed under an acceptable license (see [BIP Licensing](#bip-licensing) below). + +#### BIP Header Preamble + +Each BIP must begin with an [RFC 822-style header preamble](https://www.w3.org/Protocols/rfc822/). The headers must +appear in the following order. Headers marked with "\*" are optional. All other headers are required. + +##### Overview + +``` + BIP: +* Layer: + Title: + Authors: +* Deputies: + Status: + Type: + Created: + License: +* License-Code: +* Discussion: +* Version: +* Requires: +* Replaces: +* Proposed-Replacement: +``` + +##### Header Descriptions + +* BIP — The assigned number of the BIP. Please use "?" before a number has been assigned by the BIP Editors. +* Layer — The layer of Bitcoin the BIP applies to using the BIP classification defined in [BIP 123](bip-0123.mediawiki). +* Authors — The names (or pseudonyms) and email addresses of all authors of the BIP. The format of each authors header + value must be + + Random J. User + + Multiple authors are recorded on separate lines: + + Authors: Random J. User + Anata Sample + +* Deputies — Additional owners of the BIP that are not authors. The Deputies header uses the same format as the + Authors header. See the [BIP Ownership](#bip-ownership) section above. +* Status — The stage of the workflow of the proposal. See the [Workflow](#workflow) section below. +* Type — See the [BIP Types](#bip-types) section below for a description of the three BIP types. +* License and License-Code — These headers list SPDX License Identifier(s) of the acceptable licenses under which the + BIP and corresponding code are available. See the [BIP Licensing](#bip-licensing) section below for a description of + the Licenses and their SPDX License Identifiers. If there are multiple acceptable licenses, each should be on a + separate line. +* Discussion — The Discussion header points the audience to relevant discussions of the BIP, e.g., the mailing list + thread in which the idea for the BIP was discussed, a thread where a new version of the BIP was presented, or relevant + discussion threads on other platforms. Entries take the format "yyyy-mm-dd: URL", e.g., `2009-01-09: + https://www.mail-archive.com/cryptography@metzdowd.com/msg10142.html`, using the date and URL of the start of the + conversation. Multiple discussions should be listed on separate lines. +* Version — The current version number of this BIP. See the [Changelog](#changelog) section below. +* Requires — A list of existing BIPs the new proposal depends on. If multiple BIPs + are required, they should be listed in one line separated by a comma and space (e.g., "1, 2"). +* Replaces — BIP authors may place the numbers of one or more prior BIPs in the Replaces header to recommend that their + BIP succeeds, supersedes, or renders obsolete those prior BIPs. +* Proposed-Replacement[^superseded-by-proposed-replacement] — When a later BIP indicates that it intends to supersede an + existing BIP, the later BIP’s number is added to the Proposed-Replacement header of the existing BIP to indicate the + potential successor BIP. + +#### Auxiliary Files + +BIPs may include auxiliary files such as diagrams and source code. Auxiliary files must be included in a subdirectory +for that BIP named `bip-XXXX`, where "XXXX" is the BIP number zero-padded to four digits. File names in the subdirectory +do not need to adhere to a specific convention. + +### BIP Types + +* A **Specification BIP** defines a set of technical rules describing a new feature or affecting the interoperability of implementations. The + distinguishing characteristic of a Specification BIP is that it can be implemented, and implementations can be compliant with + it. Specification BIPs must have a Specification section, must have a Backward Compatibility section (if incompatibilities are introduced), and can only be advanced to Complete after they contain or refer to a reference implementation and test vectors. +* An **Informational BIP** describes a Bitcoin design issue, or provides general guidelines or other information to the + Bitcoin community. +* A **Process BIP** describes a process surrounding Bitcoin, or proposes a change to (or an event in) a process. Process + BIPs are like Specification BIPs, but apply to topics other than the Bitcoin protocol and Bitcoin implementations. + They often require community consensus and are typically binding for the corresponding process. Examples include + procedures, guidelines, and changes to decision-making processes such as the BIP Process. + +## Workflow + +The BIP process starts with a new idea for Bitcoin. Each potential BIP must have authors—people who write the BIP, +gather feedback, shepherd the discussion in the appropriate forums, and finally recommend a mature proposal to the +community. + +![Status Diagram](bip-0003/status-diagram.png "Status Diagram for the BIP Workflow") + +### Ideation + +After having an idea, the authors should evaluate whether it meets the criteria to become a BIP, as described in this +BIP. The idea must be of interest to the broader community or relevant to multiple software projects. Minor improvements +and matters concerning only a single project usually do not require standardization and should instead be brought up directly to +the relevant project. + +The authors should first research whether an idea has been considered before. Ideas in Bitcoin are often rediscovered, +and prior related discussions may inform the authors of the issues that may arise in its progression. After some investigation, +the novelty of an idea can be tested by posting about it to the [Bitcoin Development Mailing +List](https://groups.google.com/g/bitcoindev). Prior correspondence can be found in the [mailing list +archive](https://gnusha.org/pi/bitcoindev/). + +Vetting an idea publicly before investing the time to describe the idea formally is meant to save both the authors and +the broader community time. Not only may someone point out relevant discussion topics that were missed in the authors’ +research, or that an idea is guaranteed to be rejected based on prior discussions, but describing an idea publicly also +tests whether it is of interest to more people besides the authors. After establishing that the idea may be of interest +to the Bitcoin community, the authors should work on drafting a BIP. + +As a first sketch of the proposal is taking shape, the authors should present it to the [Bitcoin Development Mailing +List](https://groups.google.com/g/bitcoindev). This gives the authors a chance to collect initial feedback and address +fundamental concerns. If the authors wish to work in public on the proposal at this stage, it is recommended that they +open a pull request against one of their forks of the BIPs repository instead of the main BIPs repository. + +It is recommended that complicated proposals be split into separate BIPs that each focus on a specific component of the +overall proposal. + +### Progression through BIP Statuses + +The following sections refer to BIP Status Field values. The BIP Status Field is defined in the Header Preamble +specification above. + +#### Draft + +After fleshing out the proposal further and ensuring that it is of high quality and properly formatted, the authors +should open a pull request to the [BIPs repository](https://github.com/bitcoin/bips). The document must adhere to the +formatting requirements specified above and should be provided as a file named with a working title of the form +"bip-title.[md|mediawiki]". The authors must not self-assign a number to their proposal. + +BIPs that (1) adhere to the formatting requirements, (2) are on-topic, and (3) have materially progressed beyond the +ideation phase, e.g., by generating substantial public discussion and commentary from diverse contributors, by +independent Bitcoin projects working on adopting the proposal, or by the authors working for an extended period toward +improving the proposal based on community feedback, will be assigned a number by a BIP editor. The BIP editors should +delay number assignment when they perceive a proposal being met with lack of interest: number assignment facilitates the +distributed discussion of ideas, but before a proposal garners some interest in the Bitcoin community, there is no need +to refer to it by a number. + +Proposals are also not ready for number assignment if they duplicate efforts, disregard formatting rules, are too +unfocused or too broad, fail to provide proper motivation, fail to address backward compatibility where necessary, or +fail to specify the feature clearly and comprehensively. Reviewers and BIP editors should provide guidance on how the +proposal may be improved to progress toward readiness. Pull requests that are proposing off-topic ideas or +have stopped making progress may be closed. + +When the proposal is ready and has been assigned a number, a BIP editor will merge it into the BIPs repository. After the +BIP has been merged to the repository, its main focus should no longer shift significantly, even while the authors may +continue to update the proposal as necessary. Updates to merged documents by the authors should also be submitted as +pull requests. + +#### Complete[^complete] + +When the authors have concluded all planned work on their proposal, are confident that their BIP represents a net +improvement, is clear, comprehensive, and is +ready for adoption by the Bitcoin community, they may update the BIP’s status to Complete to indicate that they +recommend adoption, implementation, or deployment of the BIP. Where applicable, the authors must ensure that any +proposed specification is solid, not unduly complicated, and definitive. Specification BIPs must come with or refer to a working reference implementation and comprehensive test vectors before they can be moved to Complete. Subsequently, the BIP’s content should only be +adjusted in minor details, e.g., to improve language, clarify ambiguities, backfill omissions in the specification, add +test vectors for edge cases, or address other issues discovered as the BIP is being adopted. + +A Complete BIP can only move to Deployed or Closed. Any necessary changes to the specification should be minimal and +interfere as little as possible with ongoing adoption. If a Complete BIP is found to need substantial functional +changes, it may be preferable to move it to Closed[^new-BIP], and to start a new BIP with the changes instead. +Otherwise, it could cause confusion as to what being compliant with the BIP means. + +A BIP may remain in the Complete status indefinitely unless its authors decide to move it to Closed or it is advanced to +Deployed. +Complete is the final status for most successful Informational BIPs. + +#### Deployed + +A settled[^settled] BIP may be advanced to Deployed upon request by any community member with evidence[^evidence] that the idea +described in the BIP is in active use. Convincing evidence includes for example: an established project having deployed support +for the BIP in mainnet software releases, a soft fork proposal’s activation criteria having been met on the network, or +rough consensus for the BIP having been demonstrated. + +At that point, the BIP should be considered final and any breaking changes to the BIP should be proposed as a new +separate BIP.[^new-BIP] + +##### Process BIPs + +A Process BIP may change status from Complete to Deployed when it achieves rough consensus on the Bitcoin Development Mailing List. Such a +proposal is said to have rough consensus if it has been open to discussion on the mailing list for at least +one month, and no person maintains any unaddressed substantiated objections to it. Addressed or obstructive objections +may be ignored/overruled by general agreement that they have been sufficiently addressed, but clear reasoning must be +given in such circumstances. Deployed Process BIPs may be modified indefinitely as long as a proposed modification has +rough consensus per the same criteria.[^living-documents] + +#### Closed[^closed] + +A BIP that is of historical interest only, and is not being actively worked on, promoted or in active use, should be +marked as Closed. The reason for moving the +proposal to (or from) Closed should be recorded in the Changelog section in the same commit that updates the status. +BIPs do not get deleted, they are retained even after being updated to Closed. +Transitions involving the Closed state are: + +##### Draft ↦ Closed + +BIP authors may decide on their own to change their BIP’s status from Draft to Closed. If a Draft BIP stops making +progress, sees accumulated feedback unaddressed, or otherwise appears stalled for a year, the community may move the BIP +to Closed unless the authors assert that they intend to continue work within four weeks of being contacted. + +##### Complete ↦ Closed + +BIPs that had attained the Complete status, i.e., that had been recommended for adoption, may be moved to Closed per the +authors’ announcement to the Bitcoin Development Mailing List[^bip-announcements-to-list]. However, if someone volunteers to adopt the proposal +within four weeks, they become the BIP's author or deputy, and the BIP will +remain Complete instead. + +##### Deployed ↦ Closed + +A BIP may evolve from Deployed to Closed when it is no longer in active use. Any community member may initiate this +Status update by announcing it to the mailing list[^bip-announcements-to-list], and proceed if no objections have been raised for four weeks. + +##### Closed ↦ Draft + +The Closed status is generally intended to be a final status for BIPs, +and if BIP authors decide to make another attempt at a previously Closed BIP, it is generally recommended to create a new +proposal. (Obviously, the authors may borrow any amount of inspiration or actual text from any prior BIPs as licensing +permits.) The authors should take special care to address the issues that caused the prior attempt’s abandonment. Even +if the prior attempt had been assigned a number, the new BIP will generally be assigned a distinct number. However, if it is +obvious that the new attempt directly continues work on the same idea, it may be reasonable to return the +Closed BIP to Draft status. + +### Changelog + +To help implementers understand updates to a BIP, any changes after it has reached Complete must be tracked with version, +date, and description in a Changelog section sorted by most recent version first. The version number is inspired by semantic versioning (MAJOR.MINOR.PATCH). +The MAJOR version is incremented if changes to the BIP’s Specification are introduced that are incompatible with prior +versions (which should be rare after a BIP is Complete, and only happen in well-grounded exceptional cases to a BIP that +is Deployed). The MINOR version is incremented whenever the specification of the BIP is changed or extended in a +backward-compatible way. The PATCH version is incremented for other changes to the BIP that are noteworthy (bug fixes, +test vectors, important clarifications, etc.). Version 1.0.0 is used to label the promotion to +Complete. A Changelog section may be introduced during the Draft phase to record significant changes (using versions 0.x.y). + +Example: + +> __Changelog__ +> +> * __2.0.0__ (2025-01-22): +> * Introduce a breaking change in the specification to fix a bug. +> * __1.1.0__ (2025-01-17): +> * Add a backward compatible extension to the BIP. +> * __1.0.1__ (2025-01-15): +> * Clarify an edge case and add corresponding test vectors. +> * __1.0.0__ (2025-01-14): +> * Complete planned work on the BIP. + +After a BIP receives a Changelog, the +Preamble must indicate the latest version in the Version header. The Changelog highlights revisions to BIPs to human readers. A single +BIP shall not recommend more than one variant of an idea at the same time. A different or +competing variant of an existing BIP must be published as a separate BIP. + +### Adoption of Proposals + +The BIPs repository does not track the sentiment on proposals and does not track the adoption of BIPs beyond whether they +are in active use or not. It is not intended for BIPs to list additional implementations beyond the reference +implementation: the BIPs repository is not a signpost where to find implementations.[^OtherImplementations] After a BIP +is advanced to Complete, it is up to the Bitcoin community to evaluate, adopt, ignore, or reject a BIP. Individual +Bitcoin projects are encouraged to publish a list of BIPs they implement. A good example of this at the time of writing +this BIP can be observed in Bitcoin Core’s [doc/bips.md](https://github.com/bitcoin/bitcoin/blob/master/doc/bips.md) +file. + +### Transferring BIP Ownership + +It occasionally becomes necessary to transfer ownership of BIPs to new owners. In general, it would be preferable to +retain the original authors of the transferred BIP, but that is up to the original authors. A good reason to transfer +ownership is because the original authors no longer have the time or interest in updating it or following through with +the BIP process, or are unreachable or unresponsive. A bad reason +to transfer ownership is because someone doesn't agree with the direction of the BIP. The community tries to build +consensus around a BIP, but if that's not possible, rather than fighting over control, the dissenters should supply a +competing BIP. + +If someone is interested in assuming ownership of a BIP, they should send an email asking to take over, addressed to the +original authors, the BIP Editors, and the Bitcoin Development Mailing List[^bip-announcements-to-list]. If the authors are unreachable or do not respond in a timely +manner (e.g., four weeks), the BIP editors will make a unilateral decision whether to appoint the applicants as +[Authors or Deputies](#authors-and-deputies) (which may be amended should the original authors make a delayed reappearance). + +## BIP Licensing + +The Bitcoin project develops a global peer-to-peer digital cash system. Open standards are indispensable for continued +interoperability. Open standards reduce friction, and encourage anybody and everyone to contribute, compete, and +innovate on a level playing field. Only freely licensed contributions are accepted to the BIPs repository. + +### Specification + +Each new BIP must identify at least one acceptable license in its preamble. Licenses must be referenced per their +respective [SPDX License identifier](https://spdx.org/licenses). New BIPs may be accepted with the licenses described +below. + +For example, a preamble might include the following License header: + + License: CC0-1.0 + GNU-All-Permissive + +In this case, the BIP text is fully licensed under both the Creative Commons CC0 1.0 Universal license as well as the +GNU All-Permissive License, and anyone may modify and redistribute the text provided they comply with the terms of +*either* license. In other words, the license list is an "OR choice", not an "AND also" requirement. + +It is also possible to license source code differently from the BIP text by including the optional License-Code header +after the License header. Again, each license must be referenced by their respective SPDX License identifier shown +below. + +Each source code file or source directory should specify the license under which it is made available as is common in +software (e.g., with a license header or a LICENSE/COPYING file). It is recommended to make any test vectors available +under CC0-1.0 or GNU-All-Permissive in addition to any other licenses to allow anyone to copy test vectors into their +implementations without introducing license hindrances. Licenses listed in the License-Code header apply to all source +directories, source code files, and test vectors provided with the BIP except those where a LICENSE file in a directory +or the file header states otherwise. + +For example, a preamble specifying the optional License-Code header might look like: + + License: CC0-1.0 + License-Code: MIT + +In this case, the code in the BIP is not available under CC0-1.0, but is only available under the terms of the MIT +License. + +BIPs are not required to be *exclusively* licensed under approved terms, and may also be licensed under unacceptable +licenses *in addition to* at least one acceptable license. In this case, only the acceptable license(s) should be listed +in the License and License-Code headers. + +It is recommended that BIPs that include literal code be licensed under the same license terms as the project it +modifies. For example, literal code intended for Bitcoin Core would ideally be licensed (or dual-licensed) under the MIT +license terms. + +In all cases, details of the licensing terms must be provided in the Copyright section of the BIP. + +#### Acceptable Licenses[^licenses] + +* BSD-2-Clause: [OSI-approved BSD 2-clause license](https://opensource.org/licenses/BSD-2-Clause) +* BSD-3-Clause: [OSI-approved BSD 3-clause license](https://opensource.org/licenses/BSD-3-Clause) +* CC0-1.0: [Creative Commons CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) +* GNU-All-Permissive: [GNU All-Permissive License](http://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html) +* CC-BY-4.0: [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/) +* MIT: [Expat/MIT/X11 license](https://opensource.org/licenses/MIT) +* Apache-2.0: [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0) +* BSL-1.0: [Boost Software License, version 1.0](http://www.boost.org/LICENSE_1_0.txt) + +#### Not Acceptable Licenses + +All licenses not explicitly included in the above lists are not acceptable terms for a Bitcoin Improvement Proposal. +However, BIPs predating the acceptance of this BIP were allowed under other terms, and should use these abbreviations +when no other license is granted: + +* PD: Released into the public domain +* OPL: [Open Publication License, version 1.0](http://opencontent.org/openpub/) + +## BIP Editors + +The current BIP editors are: + +* Bryan Bishop ([kanzure@gmail.com](mailto:kanzure@gmail.com)) +* Jon Atack ([jon@atack.com](mailto:jon@atack.com)) +* Luke Dashjr ([luke_bipeditor@dashjr.org](mailto:luke_bipeditor@dashjr.org)) +* Mark "Murch" Erhardt ([murch@murch.one](mailto:murch@murch.one)) +* Olaoluwa Osuntokun ([laolu32@gmail.com](mailto:laolu32@gmail.com)) +* Ruben Somsen ([rsomsen@gmail.com](mailto:rsomsen@gmail.com)) + +### BIP Editor Responsibilities and Workflow + +The BIP editors subscribe to the Bitcoin Development Mailing List and watch the [BIPs +repository](https://github.com/bitcoin/bips). + +When a new BIP idea is submitted to the mailing list, BIP editors and other community members should comment in regard +to: + +* Novelty of the idea +* Viability, utility, and relevance of the concept +* Readiness of the proposal +* On-topic for the Bitcoin community + +Discussion in pull request comments can often be hard to follow as feedback gets marked as resolved when it is addressed +by authors. Substantive discussion of ideas may be more accessible to a broader audience on the mailing list, where it +is also more likely to be retained by the community memory. + +If the BIP needs more work, an editor should ensure that constructive, actionable feedback is provided to the authors +for revision. Once the BIP is ready it should be submitted as a "pull request" to the [BIPs +repository](https://github.com/bitcoin/bips) where it may get further feedback. + +For each new BIP pull request that comes in, an editor checks the following: + +* The idea has been previously discussed on the Bitcoin Development Mailing List +* Title accurately describes the content +* Proposal is of general interest and/or pertains to more than one Bitcoin project/implementation +* Document is properly formatted +* Licensing terms are acceptable +* Motivation, Rationale, and Backward Compatibility have been addressed +* Specification provides sufficient detail for implementation +* The defined Layer header must be correctly assigned for the given specification +* The BIP is ready: it is comprehensible, technically feasible, and all aspects are addressed as necessary + +Editors do NOT evaluate whether the proposal is likely to be adopted. + +A BIP editor will: + +* Assign a BIP number and BIP type in the pull request +* Ensure that the BIP is listed in the [README](README.mediawiki) +* Merge the pull request when it is ready + +The BIP editors are intended to fulfill administrative and editorial responsibilities. The BIP editors monitor BIP +changes, and update BIP headers as appropriate. + +BIP editors may also, at their option, unilaterally make and merge strictly editorial changes to BIPs, such as +correcting misspellings, fixing broken links, etc. as long as they do not change the meaning or conflict with the +original intent of the authors. Such a change must be recorded in the Changelog if it’s noteworthy per the criteria +mentioned in the [Changelog](#changelog) section. + +## Backward Compatibility + +### Changes from BIP 2 + +#### Workflow + +- Status field values are reduced from nine to four: + - Deferred, Obsolete, Rejected, Replaced, and Withdrawn are gathered up into Closed.[^closed] + - Final and Active are collapsed into Deployed. + - Proposed is renamed to Complete. + - The remaining statuses are Draft, Complete, Deployed, and Closed. +- The comment system is abolished.[^comments] +- A BIP in Draft or Complete status may no longer be closed solely on grounds of not making progress for three years.[^rejection] + - A BIP in Draft status may be set to Closed by anyone if it appears to have stopped making progress for at least a + year and its authors do not assert that they are still working on it when contacted. + - Complete BIPs can only be moved to Closed by its authors and may remain in Complete indefinitely. +- Process BIPs are living documents that do not ossify and may be modified indefinitely. +- Some judgment calls previously required from BIP Editors are reassigned either to the BIP authors or the repository’s + audience. + +#### BIP Format + +- The Standards Track type is superseded by the similar Specification type.[^standard-track] +- Many sections are declared optional, it is up to the authors and audience to judge whether all relevant topics have + been comprehensively addressed and which topics require a designated section to do so. +- "Other Implementations" sections are discouraged.[^OtherImplementations] +- Auxiliary files are only permitted in the corresponding BIP’s subdirectory, as no one used the alternative of labeling + them with the BIP number. +- Tracking of adoption, acceptance, and community consensus is out of scope for the BIPs repository, except to determine + whether a BIP is in active use for the move into or out of the Deployed status. +- The distinction between recommended and acceptable licenses was dropped. +- Most licenses that have not been used in the BIP process have been dropped from the list of acceptable licenses. + +#### Preamble + +- Comments-URI and Comment-Summary headers are dropped from the preamble.[^comments] +- The "Superseded-By" header is replaced with the "Proposed-Replacement" header. +- The "Post-History" header is replaced with the "Discussion" header. +- The "Discussions-To" header is dropped as it has never been used in any BIP. +- Introduce Deputies and optional Deputies header. +- Titles may now be up to 50 characters. +- Layer header is optional for Specification BIPs or Informational BIPs, as it does not make sense for all BIPs.[^layer] +- Rename "Author" field to "Authors". + +### Updates to Existing BIPs should this BIP be Activated + +#### Previous BIP Process + +This BIP supersedes BIP 2 as the guideline for the BIP process. + +#### BIP Types + +Standards Track BIPs and eligible Informational BIPs are assigned the Specification type. The Standards Track type is +considered obsolete. Specification BIPs use the Layer header rules specified in [BIP 123](BIP-0123.mediawiki). + +#### Comments + +The Comments-URI and Comment-Summary headers should be removed from all BIPs whose comment page in the wiki is empty. +For existing BIPs whose comment page has content, BIP Authors may keep both headers or remove both headers at their +discretion. It is recommended that existing wiki pages are not modified due to the activation of this BIP. + +#### Status Field + +After the activation of this BIP, the Status fields of existing BIPs that do not fit the specification in this BIP are +updated to the corresponding values prescribed in this BIP. BIPs that have had Draft status for extended periods will be +moved to Complete or Deployed as applicable in collaboration with their authors. The authors of incomplete Draft BIPs +will be contacted to learn whether the BIPs are still in progress toward Complete, and will otherwise be updated to +Closed as described in the [Workflow](#workflow) section above. + +#### Authors Header + +The Author header is replaced with the Authors header in all BIPs. + +#### Discussion Header + +The Post-History header is replaced with the Discussion header in all BIPs. + +#### Proposed-Replacement Header + +The Superseded-By header is replaced with the Proposed-Replacement header in all BIPs. + +#### Licenses + +The licenses of existing BIPs remain untouched. + +## Copyright + +This BIP is licensed under the [BSD-2-Clause License](https://opensource.org/licenses/BSD-2-Clause). Some content was +adapted from [BIP 2](BIP-0002.mediawiki) which was also licensed under the BSD-2-Clause. + +## Related Work + +- [BIP 1: BIP Purpose and Guidelines](bip-0001.mediawiki) +- [BIP 2: BIP Process, revised](BIP-0002.mediawiki) +- [BIP 123: BIP Classification](BIP-0123.mediawiki) +- [RFC 822: Standard for ARPA Internet Text Messages](https://datatracker.ietf.org/doc/html/rfc822) +- [RFC 2223: Instructions to RFC Authors](https://datatracker.ietf.org/doc/html/rfc2223) +- [RFC 7282: On Consensus and Humming in the IETF](https://tools.ietf.org/html/rfc7282) + +## Acknowledgements + +We thank AJ Towns, Jon Atack, Jonas Nick, Larry Ruane, Pieter Wuille, Tim Ruffing, and others for their review, +feedback, and helpful comments. + +## Rationale + +[^capitalization]: **When is Bitcoin capitalized and when is it lowercased?** + This document uses capitalized Bitcoin to refer to the system, network and abstract concept, and only uses lowercase + bitcoin to refer to units of the bitcoin currency. +[^standard-track]: **Why was the Specification type introduced?** + The definitions of Informational and Standards Track BIPs caused some confusion in the past. Due to Informational + BIPs being described as optional, Standards Track BIPs were sometimes misunderstood to be generally recommended. + This has led to a number of BIPs that propose new features affecting interoperability of implementations being + assigned the Informational type. The situation is remedied by introducing a new _Specification BIP_ type that is + inclusive of any BIPs that can be implemented and affect interoperability of Bitcoin applications. Since all BIPs + are individual recommendations by the authors (even if some may eventually achieve endorsement by the majority of + the community), the prior reminder that Informational BIPs are optional is dropped. +[^comments]: **Why were comments, Comments-URI, and Comment-Summary removed from the process?** + The comments feature saw insignificant adoption. Few BIPs received any comments and barely any more than two with + only a handful of contributors commenting at all. This led to many situations in which one or two comments ended up + dominating the comment summary. While some of those comments may have been representative of broadly held opinions, + it also overstated the importance of individual comments directly in the Preamble of BIPs. As collecting feedback in + this accessible fashion failed, the new process puts the onus back on the audience to make their own evaluation. +[^layer]: **Why is the layer header now permitted for other BIP types?** + The layer header had already been used by many Informational BIPs, so the rule that it is only available to + Standards Track BIPs is dropped. +[^OtherImplementations]: **What is the issue with "Other Implementations" sections in BIPs?** + In the past, some BIPs had "Other Implementations" sections that caused frequent change requests to existing BIPs. + This put an onus on the BIP authors, and frequently led to lingering pull requests due to the corresponding BIPs’ + authors no longer participating in the process. Many of these alternative implementations eventually became + unmaintained or were low-quality to begin with. Therefore, "Other Implementations" sections are heavily discouraged. +[^complete]: **Why was the Proposed status renamed to Complete?** + Some reviewers of this BIP raised that in a process which outlines the workflow of Bitcoin Improvement _Proposals_ + using "Proposed" as a status field value was overloading the term: clearly _proposals_ are proposed at all stages of + the process. "Complete" expresses that the authors have concluded planned work on all parts of the proposal and are + ready to recommend their BIP for adoption. The term "ready" was also considered, but considered too subjective. +[^rejection]: **Why can proposals remain in Draft or Complete indefinitely?** + The automatic 3-year timeout of BIPs has led to some disagreement in the past and seems unnecessary in cases where + the authors are still active in the community and still consider their idea worth pursuing. On the other hand, + Draft proposals that appear stale may be tested and cleared out after only one year which should achieve the main goal of + the original rule by limiting the effort and attention spent on proposals that never reach Complete. +[^closed]: **Why was the Closed Status introduced?** + The Closed Status provides value to the audience by indicating which documents are only of historical significance. + Previously, the process had Deferred, Obsolete, Rejected, Replaced, and Withdrawn which all meant some flavor of + "work has stopped on this". The many statuses complicated the process, may have contributed to process fatigue, and + may have resulted in BIPs’ statuses not being maintained well. The author of this BIP feels that all of the + aforementioned can be represented by _Closed_ without significantly impacting the information quality of the + overview table. Where the many Status variants provided minuscule additional information, the simplification is more + valuable and the Changelog section now collects specific details. +[^acceptance]: **Why does the BIPs repository no longer track adoption?** + BIP 2 made an attempt to gather community feedback into comment summaries in BIPs directly. Given the low adoption + and corresponding low information quality of the summaries that resulted from that feature, this BIP instead intends + to leave the evaluation of BIPs to the audience. +[^markdown]: **Which flavor of Markdown is allowed?** + The author of this proposal has no opinion on Markdown flavors, but recommends that proposals stick to the basic + Markdown syntax features commonly shared across Markdown dialects. +[^living-documents]: **Why are Process BIPs living documents?** + In the past years, the existing BIPs process has not always provided a clear approach to all situations. For + example, the content of BIP 2 appears to have been penned especially with fork proposals in mind. It seems clear + that Bitcoin development will evolve in many surprising ways in the future. Instead of mandating the effort of + writing a new process document every time new situations arise, it seems preferable to allow the process to adapt to + the concerns of the future in specific aspects. Therefore, Process BIPs are defined as living documents that remain + open to amendment. If a Process BIP requires large modifications or even a complete overhaul, a new BIP should be + preferred. +[^new-BIP]: **Why should the specification of an implemented BIP no longer be changed?** + After a Complete or Deployed BIP has been deployed by one or more implementations, breaking changes to the + specification could lead to a situation where multiple "compliant" implementations fail at being interoperable, + because they implemented different versions of the same BIP. Therefore, even changes to the specification of + Complete BIPs should be avoided, but Deployed BIPs should never be subject to breaking changes to their + specification. +[^settled]: **What is meant by a BIP being settled?** + Since Deployed BIPs should not be changed, a Complete BIP should only be moved to Deployed after its Specification + has been put through its paces and changes to the BIP have stopped. +[^bip-announcements-to-list]: **Why are some BIP status changes announced to the mailing list?** + The BIPs repository does not and cannot track who might be interested in or has deployed a BIP. While concerns were + raised that making announcements to the Bitcoin Developer Mailing List would introduce unnecessary noise, our + rationale is that 1) moving Complete and Deployed BIPs to the Closed status will be a rare occurrence, 2) status + updates will usually not generate a lot of discussion, 3) while the mailing list should preferably only used for + getting review for new BIPs, it is the only channel available to us that can be consider a public announcement to + the audience of the BIPs repository: even if the authors, implementers, or other parties interested in a BIP do not + see the announcement themselves, they may be made aware by someone that does see it. +[^superseded-by-proposed-replacement]: **Why is Superseded-By replaced with Proposed-Replacement?** + Reviewers asked who should get to decide whether a BIP is superseded in case of a disagreement among the authors of + the original BIP, the authors of the new BIP, the editors, or the community? This is addressed by making the + "Replaces" header part of the recommendation of the authors of the new document, and replacing the "Superseded-By" + header with the "Proposed-Replacement" header that lists any proposals that recommend replacing the original document. +[^evidence]: **How is evidence for advancing to Deployed evaluated?** + Whether evidence is deemed convincing to move a BIP to Deployed is up to the BIP Editors and Bitcoin community. + Running a single instance of a personal fork of a software project might be rejected, while a small software project with + dozens of users may be sufficient. The main point of the Deployed status is to indicate that changes to the BIP + could negatively impact users of projects that have already implemented support. +[^licenses]: **Why were some licenses dropped?** + Among the 141 BIPs with licenses in the repository, only nine licenses have ever been used to license BIPs + (although, some BIPs were made available under more than one license) and only one license has been used to license + code: + + Licenses used: + + * BSD-2-Clause: 55 + * PD: 42 + * CC0-1.0: 23 + * BSD-3-Clause: 19 + * OPL: 5 + * CC-BY-SA-4.0: 4 + * GNU-All-Permissive: 3 + * MIT: 2 + * CC-BY-4.0: 1 + + License-Code used: + + * MIT: 4 + + The following previously acceptable licenses were retained per request of reviewers, even though they have so far + never been used in the BIPs process: + + * Apache-2.0: [Apache License, version 2.0](http://www.apache.org/licenses/LICENSE-2.0) + * BSL-1.0: [Boost Software License, version 1.0](http://www.boost.org/LICENSE_1_0.txt) + + The following previously acceptable licenses have never been used in the BIPs Process and have been dropped: + + * AGPL-3.0+: [GNU Affero General Public License (AGPL), version 3 or newer](http://www.gnu.org/licenses/agpl-3.0.en.html) + * FDL-1.3: [GNU Free Documentation License, version 1.3](http://www.gnu.org/licenses/fdl-1.3.en.html) + * GPL-2.0+: [GNU General Public License (GPL), version 2 or newer](http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) + * LGPL-2.1+: [GNU Lesser General Public License (LGPL), version 2.1 or newer](http://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html) + + Why are software licenses included? + + * Some BIPs, in particular those concerning the consensus layer, may include literal code in the BIP itself which + may not be available under the license terms the authors wish to use for the BIP. + * The author of this BIP has been provided with a learned opinion indicating that software licenses are perfectly + acceptable for licensing "human code" i.e., text as well as Markdown or MediaWiki code. + + Why is CC-BY-SA-4.0 no longer acceptable for new BIPs? + + * Specification BIPs are required to have a Reference Implementation and Test Vectors to be advanced to Complete. As + the BIPs repository is aiming to make proposals easily adoptable, the intention is for the reference + implementation and test vectors to be as accessible as possible. Copyleft licenses may introduce friction here, + and therefore CC-BY-SA-4.0 (and the GPL-flavors) is no longer considered acceptable for new BIPs. As mentioned + above, existing BIPs will retain their original licensing. + + Why are OPL and Public Domain no longer acceptable for new BIPs? + + * Public domain is not universally recognised as a legitimate action, thus it is inadvisable. + * The OPL is generally regarded as obsolete, and not a license suitable for new publications. diff --git a/bip-0003/status-diagram.png b/bip-0003/status-diagram.png new file mode 100644 index 00000000..acddba63 Binary files /dev/null and b/bip-0003/status-diagram.png differ