From 2c57d8aee6ba6a4568d0f5c527241b6664f16191 Mon Sep 17 00:00:00 2001 From: Murch Date: Fri, 20 Jun 2025 15:56:58 -0700 Subject: [PATCH 1/5] bip3: Fix minor phrasing and structure issues --- bip-0003.md | 63 +++++++++++++++++++++++++++-------------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/bip-0003.md b/bip-0003.md index 1624e50e65..61e9cf054f 100644 --- a/bip-0003.md +++ b/bip-0003.md @@ -24,13 +24,13 @@ address the evolving needs of the BIP process. 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. +BIP types more clearly, and generalizes the BIP process to fit 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 +BIPs are improvement proposals for Bitcoin[^capitalization]. 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 @@ -39,7 +39,7 @@ the Bitcoin protocol, peer-to-peer network, and client software may be acceptabl 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 +The scope of the BIPs 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. @@ -48,7 +48,7 @@ electronic cash system for the bitcoin currency. 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. +co-owned by the Bitcoin community. #### Authors and Deputies @@ -181,7 +181,7 @@ do not need to adhere to a specific convention. * 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. + procedures, guidelines, and changes to decision-making processes such as the BIP process. ## Workflow @@ -220,7 +220,7 @@ 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 +The following sections refer to BIP Status field values. The BIP Status field is defined in the Header Preamble specification above. #### Draft @@ -233,18 +233,18 @@ formatting requirements specified above and should be provided as a file named w 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 +improving the proposal based on community feedback, will be assigned a number by a BIP Editor. The BIP Editors should +not assign a number 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 +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 +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. @@ -264,25 +264,29 @@ interfere as little as possible with ongoing adoption. If a Complete BIP is foun 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 +A BIP may remain in the Complete status indefinitely unless its authors or deputies 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 +A Complete BIP should only be moved to Deployed once it is settled: after its approach has solidified, its +Specification has been put through its paces, feedback from early adopters has been processed, and amendments to the BIP have stopped. +Then, a BIP may be advanced to Deployed upon request by any community member with evidence[^evidence] that +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] +Once Deployed, the BIP is considered final. +Any modifications to the BIP beyond bug fixes, other minor amendments, additions to the test vectors, or editorial +changes should be avoided. +Any breaking changes to the BIP’s Specification 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 +A Process BIP may change status from Complete to Deployed when it achieves rough consensus on the Bitcoin Development Mailing List. A +proposal is said to have rough consensus if its advancement has been open to discussion on the mailing list for at least +one month, the discussion achieved meaningful engagement, 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] @@ -298,8 +302,8 @@ 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. +progress, sees accumulated feedback unaddressed, or otherwise appears stalled for a year, anyone may propose the BIP +status be updated to Closed. The BIP is then updated to Closed unless the authors assert that they intend to continue work within four weeks of being contacted. ##### Complete ↦ Closed @@ -374,7 +378,7 @@ 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 +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 @@ -441,7 +445,7 @@ In all cases, details of the licensing terms must be provided in the Copyright s #### 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 +However, BIPs predating this proposal were allowed under other terms, and should use these abbreviations when no other license is granted: * PD: Released into the public domain @@ -449,7 +453,7 @@ when no other license is granted: ## BIP Editors -The current BIP editors are: +The current BIP Editors are: * Bryan Bishop ([kanzure@gmail.com](mailto:kanzure@gmail.com)) * Jon Atack ([jon@atack.com](mailto:jon@atack.com)) @@ -460,10 +464,10 @@ The current BIP editors are: ### BIP Editor Responsibilities and Workflow -The BIP editors subscribe to the Bitcoin Development Mailing List and watch the [BIPs +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 +When either a new BIP idea or an early draft is submitted to the mailing list, BIP Editors and other community members should comment in regard to: * Novelty of the idea @@ -494,16 +498,16 @@ For each new BIP pull request that comes in, an editor checks the following: Editors do NOT evaluate whether the proposal is likely to be adopted. -Then, a BIP editor will: +Then, 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 +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 +BIP Editors may also, at their option, unilaterally make and merge strictly editorial changes to BIPs, such as correcting misspellings, mending grammar mistakes, 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. @@ -678,9 +682,6 @@ feedback, and helpful comments. 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 From 7101294a9328862a95f63175d893b53e514b05cd Mon Sep 17 00:00:00 2001 From: Murch Date: Fri, 27 Jun 2025 09:52:54 -0700 Subject: [PATCH 2/5] bip3: Describe acceptance as Adoption/Publication --- bip-0003.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/bip-0003.md b/bip-0003.md index 61e9cf054f..4f0b2dc19d 100644 --- a/bip-0003.md +++ b/bip-0003.md @@ -72,10 +72,10 @@ Through its high visibility, it facilitates the community-wide consideration of 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 stakeholders across the ecosystem. +The BIPs repository neither tracks community sentiment[^acceptance] nor ecosystem adoption[^adoption] of BIPs beyond +the brief overview provided via the BIP status (see [Workflow](#workflow) below). +Proposals are published in this repository if they are on-topic and fulfill the editorial criteria. +No formal or informal decision body governs Bitcoin development or decides adoption of BIPs. ## BIP Format and Structure @@ -540,7 +540,7 @@ mentioned in the [Changelog](#changelog) section. - "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 +- Tracking of community consensus and adoption 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. @@ -661,10 +661,19 @@ feedback, and helpful comments. 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. +[^acceptance]: **When is a BIP "accepted"?** + Many standards processes such as the PEPs or the IETF have a mechanism for a proposal to be formally accepted by + some council or committee. The BIP Process does not have such a decision body. Bitcoin development and "acceptance" + of BIPs emerges from the participation of stakeholders across the ecosystem, and refers to some vague notion of community + interest and support for a proposal. + BIP 2 had made an attempt to gather community feedback into comment summaries in BIPs directly. Given the low + participation 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 reviewers and users. +[^adoption]: **Why does the BIPs repository no longer track adoption?** + In the past, some BIPs maintained lists of projects that had implemented the BIP. These lists generated + noise for subscribers of the repository, often listed implementations of questionable quality, and quickly + grew outdated, therefore providing little value. The repository no longer tracks which projects have implemented + BIPs. Instead, it is recommended that projects publish a list of the BIPs they implement. [^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. From 66cb7504b44a04410fd2afbd2289d944e2ab36bb Mon Sep 17 00:00:00 2001 From: Murch Date: Fri, 27 Jun 2025 09:59:00 -0700 Subject: [PATCH 3/5] bip3: Explain why the Replaces header is unchanged --- bip-0003.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/bip-0003.md b/bip-0003.md index 4f0b2dc19d..8e49ab776f 100644 --- a/bip-0003.md +++ b/bip-0003.md @@ -159,7 +159,7 @@ appear in the following order. Headers marked with "\*" are optional. All other * 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 +* Replaces[^proposes-to-replace] — BIP authors may put 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 @@ -704,6 +704,16 @@ feedback, and helpful comments. 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. +[^proposes-to-replace]: **Why was "Replaces" retained instead of changing it to "Proposes-to-Replace"?** + When one BIP proposes to supersede another, it is on the original BIP where things get complicated. The BIP is an + author document, but depending on its progress through the workflow, it may meanwhile be co-owned by the community. Who may decide + whether the original document should endorse a potential replacement BIP? Is it the original authors, the authors of the new + proposal, the BIP Editors, some sort of community process, or a mix of all of the above? + On the new BIP these problems don’t exist in the same manner. As it is freshly written, it is wholly owned by its + authors. The community is not yet invested and the original BIP’s authors do not have a privileged role + in determining the content of the new BIP. The authors of the new BIP can unilaterally recommend that it be + considered a replacement for a prior BIP. From there, the community can evaluate the proposal and adopt or + reject it, thus establishing whether it is successful in superseding the original or not. [^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 From 0bbe31b7450cb153731004ae51354c5e120f6af5 Mon Sep 17 00:00:00 2001 From: Murch Date: Fri, 27 Jun 2025 10:00:06 -0700 Subject: [PATCH 4/5] bip3: Restate recommendation to get early feedback --- bip-0003.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/bip-0003.md b/bip-0003.md index 8e49ab776f..0a8506f91b 100644 --- a/bip-0003.md +++ b/bip-0003.md @@ -198,17 +198,19 @@ BIP. The idea must be of interest to the broader community or relevant to multip 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, +The authors should first research whether their 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 +the novelty and viability of the idea should be tested by posting about the idea 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’ +It is recommended that authors establish before or at the start of working on a draft whether their idea may be of +interest to the Bitcoin community. +Authors should avoid opening a pull request with a BIP draft out of the blue. +Vetting an idea publicly before investing time and effort to formally describe the idea is meant to save time for both the authors and +the community. 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. +tests whether it is of interest to more people beside the authors. 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 From 99b8541e0992cfa67ee9c7ce4980b46c3d3ce1ea Mon Sep 17 00:00:00 2001 From: Murch Date: Fri, 27 Jun 2025 10:00:47 -0700 Subject: [PATCH 5/5] bip3: Improve compatibility section --- bip-0003.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/bip-0003.md b/bip-0003.md index 0a8506f91b..5f096386ad 100644 --- a/bip-0003.md +++ b/bip-0003.md @@ -527,9 +527,10 @@ mentioned in the [Changelog](#changelog) section. - 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. + - A BIP in Draft status may be updated to Closed status if it appears to have stopped making progress for at least a + year and its authors do not assert within four weeks of being contacted that they are still working on it. - Complete BIPs can only be moved to Closed by its authors and may remain in Complete indefinitely. +- A Changelog section is introduced to track significant changes to BIPs after they have reached the Complete status. - 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. @@ -552,6 +553,7 @@ mentioned in the [Changelog](#changelog) section. - "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 optional "Version" header is introduced. - The "Discussions-To" header is dropped as it has never been used in any BIP. - Introduce Deputies and optional "Deputies" header. - The BIP "Title" header may now contain up to 50 characters (increased from 44 in BIP 2).