BIP3: Address additional review #1819

pull murchandamus wants to merge 14 commits into bitcoin:master from murchandamus:2025-03-bip3-followups changing 1 files +69 −42
  1. murchandamus commented at 10:14 pm on April 11, 2025: contributor

    BIP3 got a bit more review from @RubenSomsen, @darosior, and @jonatack. Thanks!

    This PR addresses the review. Most of it related to minor phrasing improvements, typos, and added emphasis.

    I also added mention of the Version header and Changelog to the Backward Compatibility section which I had overlooked, and explain why I consider the headers “Superseded-by” and “Replaces” asymmetric, and only propose a new name for “Superseded-by” but retain “Replaces”.

    This PR includes a deletion and readdition of the entire BIP 3, so as to provide further reviewers a surface to leave comments directly on the BIP text. These two commits will disappear without a trace when the PR is later squash-merged.

  2. Remove BIP 3 text to make it show in PR 96d127dd20
  3. Revert "Remove BIP 3 text to make it show in PR" 
    This reverts commit 96d127dd20e24cf5a99a00ab68a4c6cfeb421da3.
    3ec810e7c4
  4. BIP3: Address minor issues from Ruben’s review 81022863aa
  5. BIP3: Describe acceptance and adoption f2d7d80dc7
  6. BIP3: Explain why the Replaces header is unchanged 143066c9bd
  7. BIP3: Mention Changelog and Version in Backward Compatibility fa91a1de14
  8. murchandamus added the label Proposed BIP modification on Apr 11, 2025
  9. murchandamus added the label Process on Apr 11, 2025
  10. in bip-0003.md:207 in 81022863aa outdated 
    204-the novelty of an idea can be tested by posting about it to the [Bitcoin Development Mailing
205+the novelty and viability of the idea should be tested by posting about it to the [Bitcoin Development Mailing
206 List](https://groups.google.com/g/bitcoindev). Prior correspondence can be found in the [mailing list
207 archive](https://gnusha.org/pi/bitcoindev/).
208 
209+Authors should avoid showing up out of the blue with a BIP draft.
    darosior commented at 1:17 pm on April 14, 2025:
    :joy: :+1:
  11. darosior approved
  12. darosior commented at 1:28 pm on April 14, 2025: member
    ACK on the changes.
  13. BIP3: Replace transparent bg with white in diagram 5eaea88c77
  14. RubenSomsen commented at 5:34 pm on April 14, 2025: contributor
    Happy with the changes. I’m fully behind BIP3. Good work, Murch👍
  15. in bip-0003.md:527 in fa91a1de14 outdated 
    526@@ -527,6 +527,7 @@ mentioned in the [Changelog](#changelog) section.
527   - A BIP in Draft status may be set to Closed by anyone if it appears to have stopped making progress for at least a
    jonatack commented at 5:59 pm on April 14, 2025:
    s/A BIP in Draft status may be set to Closed by anyone/Anyone may propose that a BIP be updated to Closed status/
    murchandamus commented at 0:43 am on April 15, 2025:
    Rephrased that line
  16. in bip-0003.md:711 in 143066c9bd outdated 
    705@@ -706,6 +706,16 @@ feedback, and helpful comments.
706     the original BIP, the authors of the new BIP, the editors, or the community? This is addressed by making the
707     "Replaces" header part of the recommendation of the authors of the new document, and replacing the "Superseded-By"
708     header with the "Proposed-Replacement" header that lists any proposals that recommend replacing the original document.
709+[^proposes-to-replace]: **Why was "Replaces" retained instead of changing it to "Proposes-to-Replace"?**  
710+    When one BIP proposes to supersede another, it is on the original BIP where things get complicated. The BIP is an
711+    author document, but depending on its progress through the Workflow, it may be meanwhile co-owned by community. Who gets to decide
    jonatack commented at 6:01 pm on April 14, 2025:
    s/gets to/may/
  17. in bip-0003.md:715 in 143066c9bd outdated 
    710+    When one BIP proposes to supersede another, it is on the original BIP where things get complicated. The BIP is an
711+    author document, but depending on its progress through the Workflow, it may be meanwhile co-owned by community. Who gets to decide
712+    whether the original document should endorse a potential replacement BIP? Is it the original authors, the authors of the new
713+    proposal, the BIP Editors, some sort of community process, or a mix of all of the above?  
714+    On the new BIP these problems don’t exist in the same manner. As it is freshly written, it is wholly owned by its
715+    authors, neither is the community already invested, nor do the original BIP’s authors have a privileged role
    jonatack commented at 6:02 pm on April 14, 2025:
    “neither is” phrasing here is awkward IMO
    murchandamus commented at 0:50 am on April 15, 2025:

    Changed to

    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.

  18. in bip-0003.md:716 in 143066c9bd outdated 
    711+    author document, but depending on its progress through the Workflow, it may be meanwhile co-owned by community. Who gets to decide
712+    whether the original document should endorse a potential replacement BIP? Is it the original authors, the authors of the new
713+    proposal, the BIP Editors, some sort of community process, or a mix of all of the above?  
714+    On the new BIP these problems don’t exist in the same manner. As it is freshly written, it is wholly owned by its
715+    authors, neither is the community already invested, nor do the original BIP’s authors have a privileged role
716+    determining the content of the new BIP. The authors of the new BIP can unilaterally recommend that it should be
    jonatack commented at 6:02 pm on April 14, 2025:

    s/determining/in determining/

    s/that it should be/that it be/ (imperative, can drop the should)

    murchandamus commented at 0:50 am on April 15, 2025:
    Taken
  19. in bip-0003.md:76 in f2d7d80dc7 outdated 
    71@@ -72,10 +72,9 @@ Through its high visibility, it facilitates the community-wide consideration of
72 source to retrieve the latest version of any BIP. The repository transparently records all changes to each BIP and
73 allows any community member to retain a complete copy of the archive easily.
74 
75-The BIPs repository is not a tool to track acceptance[^acceptance], adoption, or community consensus on BIPs, beyond
76-providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.
77-There is no formal or informal decision body that governs Bitcoin development or decides acceptance of BIPs. Bitcoin
78-development emerges from the participation of stakeholders across the ecosystem.
79+The BIPs repository neither tracks community sentiment nor ecosystem adoption[^adoption] of BIPs beyond
80+the brief overview provided per the BIP statuses (see [Workflow](#workflow) below) to the audience.
    jonatack commented at 6:04 pm on April 14, 2025:

    s/per/via/

    s/statuses/status/ (there is one status per BIP)

    murchandamus commented at 11:42 pm on April 14, 2025:
    Took both and dropped the “to the audience”.
  20. in bip-0003.md:77 in f2d7d80dc7 outdated 
    76-providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.
77-There is no formal or informal decision body that governs Bitcoin development or decides acceptance of BIPs. Bitcoin
78-development emerges from the participation of stakeholders across the ecosystem.
79+The BIPs repository neither tracks community sentiment nor ecosystem adoption[^adoption] of BIPs beyond
80+the brief overview provided per the BIP statuses (see [Workflow](#workflow) below) to the audience.
81+There is no formal or informal decision body that governs Bitcoin development or decides acceptance[^acceptance] of BIPs.
    jonatack commented at 6:05 pm on April 14, 2025:
    nit, “No formal or informal decision body governs” would be more direct and concise
    murchandamus commented at 11:42 pm on April 14, 2025:
    Taken
  21. in bip-0003.md:670 in f2d7d80dc7 outdated 
    669+    some council or committee. The BIP Process does not have such a decision body. Bitcoin development and "acceptance"
670+    of BIPs emerges from the participation of stakeholders across the ecosystem, and refers to some notion of community
671+    interest and support for a proposal.  
672+    BIP 2 had made an attempt to gather community feedback into comment summaries in BIPs directly. Given the low
673+    adoption and corresponding low information quality of the summaries that resulted from that feature, this BIP
674+    instead intends to leave the evaluation of BIPs to the audience.
    jonatack commented at 6:06 pm on April 14, 2025:
    Perhaps s/the audience/reviewers and users/
    murchandamus commented at 0:45 am on April 15, 2025:
    Was also considering “to the reader”, but went with your suggestion.
  22. in bip-0003.md:673 in f2d7d80dc7 outdated 
    672+    BIP 2 had made an attempt to gather community feedback into comment summaries in BIPs directly. Given the low
673+    adoption and corresponding low information quality of the summaries that resulted from that feature, this BIP
674+    instead intends to leave the evaluation of BIPs to the audience.
675+[^adoption]: **Why does the BIPs repository no longer track adoption?**  
676+    In the past, some BIPs maintained lists of projects that had implemented the BIP. These lists generated a lot of
677+    noise to subscribers of the repository, but often listed implementations of questionable quality while quickly
    jonatack commented at 6:07 pm on April 14, 2025:
    suggest s/a lot of noise to/noise for/
  23. in bip-0003.md:674 in f2d7d80dc7 outdated 
    673+    adoption and corresponding low information quality of the summaries that resulted from that feature, this BIP
674+    instead intends to leave the evaluation of BIPs to the audience.
675+[^adoption]: **Why does the BIPs repository no longer track adoption?**  
676+    In the past, some BIPs maintained lists of projects that had implemented the BIP. These lists generated a lot of
677+    noise to subscribers of the repository, but often listed implementations of questionable quality while quickly
678+    growing outdated, therefore providing little value. The repository does not track which projects have implemented
    jonatack commented at 6:08 pm on April 14, 2025:
    s/does not track…anymore/no longer tracks/
    murchandamus commented at 0:46 am on April 15, 2025:
    Great!
  24. in bip-0003.md:33 in 81022863aa outdated 
    30 ## Fundamentals
31 
32 ### What is a BIP?
33 
34-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
35+BIPs are improvement proposals for Bitcoin[^capitalization] that cover the range of interests of the community. The main topic is information and technologies that support and expand the utility of the bitcoin
    jonatack commented at 6:10 pm on April 14, 2025:
    “the range of interests of the community” is vague and likely not helpful or could be argued over in future BIP scope discussions
    murchandamus commented at 11:38 pm on April 14, 2025:
    Dropped “that cover the range of interests of the community”
  25. in bip-0003.md:213 in 81022863aa outdated 
    212 research, or that an idea is guaranteed to be rejected based on prior discussions, but describing an idea publicly also
213-tests whether it is of interest to more people besides the authors. After establishing that the idea may be of interest
214-to the Bitcoin community, the authors should work on drafting a BIP.
215+tests whether it is of interest to more people besides the authors.
216+The authors should work on drafting a BIP only after establishing that the idea may be of interest
217+to the Bitcoin community.
    jonatack commented at 6:13 pm on April 14, 2025:
    It seems to me that authors are free to work on drafting a BIP. What we want to suggest here is that they not open a PR to propose it until establishing that the idea may be of interest to the larger Bitcoin community
    murchandamus commented at 0:06 am on April 15, 2025:
    I rewrote start and end of this paragraph.
  26. in bip-0003.md:275 in 81022863aa outdated 
    273 
274 #### Deployed
275 
276-A settled[^settled] BIP may be advanced to Deployed upon request by any community member with evidence[^evidence] that the idea
277-described in the BIP is in active use. Convincing evidence includes for example: an established project having deployed support
278+Deployed BIPs should not be changed. A Complete BIP should only be moved to Deployed once it is settled: after its
    jonatack commented at 6:15 pm on April 14, 2025:

    We may want to be clear what “changed” means here; perhaps something along the lines of:

    s/not be changed/not be changed apart from bug fixes, other minor fixes or editorial-only changes/

    murchandamus commented at 0:35 am on April 15, 2025:
    Dropped the first sentence and rewrote the last sentence.
  27. in bip-0003.md:305 in 81022863aa outdated 
    301@@ -298,7 +302,7 @@ Transitions involving the Closed state are:
302 ##### Draft ↦ Closed
303 
304 BIP authors may decide on their own to change their BIP’s status from Draft to Closed. If a Draft BIP stops making
305-progress, sees accumulated feedback unaddressed, or otherwise appears stalled for a year, the community may move the BIP
306+progress, sees accumulated feedback unaddressed, or otherwise appears stalled for a year, anyone may move the BIP
    jonatack commented at 6:18 pm on April 14, 2025:

    Perhaps

    s/anyone may move the BIP to Closed/anyone may propose the BIP status be updated to Closed/

    murchandamus commented at 0:41 am on April 15, 2025:
    Sure, taken
  28. in bip-0003.md:532 in 81022863aa outdated 
    528@@ -525,7 +529,7 @@ mentioned in the [Changelog](#changelog) section.
529     year and its authors do not assert that they are still working on it when contacted.
530   - Complete BIPs can only be moved to Closed by its authors and may remain in Complete indefinitely.
531 - Process BIPs are living documents that do not ossify and may be modified indefinitely.
532-- Some judgment calls previously required from BIP Editors are reassigned either to the BIP authors or the repository’s
533+- Some judgment calls previously required from BIP editors are reassigned either to the BIP authors or the repository’s
    jonatack commented at 6:19 pm on April 14, 2025:
    I think “BIP editors” ought to consistently be written “BIP Editors” throughout the BIP, as these are proper nouns rather than generic editors
    murchandamus commented at 0:38 am on April 15, 2025:
    Okay, done
  29. jonatack commented at 6:25 pm on April 14, 2025: member

    What is the advantage of changing the diagram to a white background? That change makes it more disagreeable to read when using GitHub in dark mode; same for use in a presentation with a dark background (as I did a few days ago).

    2025-04-12 BIP statuses

  30. jonatack commented at 6:30 pm on April 14, 2025: member
    I think this “standard-track” footnote is confusing and could made clearer. Maybe we can do a call to discuss: https://github.com/bitcoin/bips/pull/1819/files#diff-0fe6969eba0422ddb0e7823d13092c03aa90122e0c5e66786c5d8b20f54719e6R625
  31. bip3: Adopt minor suggestions from review 22235510b6
  32. bip3: Restate recommendation to get early feedback 2eb294cc27
  33. bip3: Improve description of Deployed status 2af95247e7
  34. bip3: Treat BIP Editor as proper noun 5918204746
  35. bip3: Improve phrasing in several paragraphs 6604a3dcdf
  36. murchandamus commented at 1:05 am on April 15, 2025: contributor
    Addressed @jonatack’s review comments, thanks!
  37. Revert "BIP3: Replace transparent bg with white in diagram" 
    This reverts commit 5eaea88c77e7a7802ea8edf09f1b53b74fe1db4d.
    2ecef94401
  38. in bip-0003.md:715 in 2ecef94401 outdated 
    711@@ -710,12 +712,12 @@ feedback, and helpful comments.
712     header with the "Proposed-Replacement" header that lists any proposals that recommend replacing the original document.
713 [^proposes-to-replace]: **Why was "Replaces" retained instead of changing it to "Proposes-to-Replace"?**  
714     When one BIP proposes to supersede another, it is on the original BIP where things get complicated. The BIP is an
715-    author document, but depending on its progress through the Workflow, it may be meanwhile co-owned by community. Who gets to decide
716+    author document, but depending on its progress through the Workflow, it may be meanwhile co-owned by community. Who may decide
    jonatack commented at 4:32 pm on April 15, 2025: 
    0    author document, but depending on its progress through the workflow, it may meanwhile be co-owned by the community. Who may decide
  39. in bip-0003.md:77 in 2ecef94401 outdated 
    76-providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.
77-There is no formal or informal decision body that governs Bitcoin development or decides acceptance of BIPs. Bitcoin
78-development emerges from the participation of stakeholders across the ecosystem.
79+The BIPs repository neither tracks community sentiment nor ecosystem adoption[^adoption] of BIPs beyond
80+the brief overview provided via the BIP status (see [Workflow](#workflow) below).
81+No formal or informal decision body governs Bitcoin development or decides acceptance[^acceptance] of BIPs.
    jonatack commented at 4:35 pm on April 15, 2025:

    Could “acceptance” be (mis)construed as acceptance into the BIPs repository? Perhaps “adoption” (or “community adoption”) would be a better term.

    0No formal or informal decision body governs Bitcoin development or decides adoption[^adoption] of BIPs.
  40. in bip-0003.md:161 in 2ecef94401 outdated 
    157@@ -159,7 +158,7 @@ appear in the following order. Headers marked with "\*" are optional. All other
158 * Version — The current version number of this BIP. See the [Changelog](#changelog) section below.
159 * Requires — A list of existing BIPs the new proposal depends on. If multiple BIPs
160   are required, they should be listed in one line separated by a comma and space (e.g., "1, 2").
161-* Replaces — BIP authors may place the numbers of one or more prior BIPs in the Replaces header to recommend that their
162+* Replaces[^proposes-to-replace] — BIP authors may place the numbers of one or more prior BIPs in the Replaces header to recommend that their
    jonatack commented at 4:35 pm on April 15, 2025: 
    0* Replaces[^proposes-to-replace] — BIP authors may propose the numbers of one or more prior BIPs in the Replaces header to recommend that their
  41. in bip-0003.md:208 in 2ecef94401 outdated 
    207 
208-Vetting an idea publicly before investing the time to describe the idea formally is meant to save both the authors and
209-the broader community time. Not only may someone point out relevant discussion topics that were missed in the authors’
210+It is recommended that authors establish before or at the start of working on a draft whether their idea may be of
211+interest to the Bitcoin community.
212+Vetting an idea publicly before investing time and effort to formally describe the idea is meant to save both the authors and
    jonatack commented at 4:37 pm on April 15, 2025:
    suggest “meant to save time for both the authors and the community”
  42. in bip-0003.md:212 in 2ecef94401 outdated 
    213+the community time. Not only may someone point out relevant discussion topics that were missed in the authors’
214 research, or that an idea is guaranteed to be rejected based on prior discussions, but describing an idea publicly also
215-tests whether it is of interest to more people besides the authors. After establishing that the idea may be of interest
216-to the Bitcoin community, the authors should work on drafting a BIP.
217+tests whether it is of interest to more people beside the authors.
218+Authors should avoid opening a pull request with a BIP draft out of the blue.
    jonatack commented at 4:38 pm on April 15, 2025:
    This line is perhaps a bit redundant with the preceding text. (I also don’t know how well understood “out of the blue” would be by non-native English readers.)
  43. in bip-0003.md:667 in 2ecef94401 outdated 
    663@@ -657,10 +664,19 @@ feedback, and helpful comments.
664     aforementioned can be represented by _Closed_ without significantly impacting the information quality of the
665     overview table. Where the many Status variants provided minuscule additional information, the simplification is more
666     valuable and the Changelog section now collects specific details.
667-[^acceptance]: **Why does the BIPs repository no longer track adoption?**  
668-    BIP 2 made an attempt to gather community feedback into comment summaries in BIPs directly. Given the low adoption
669-    and corresponding low information quality of the summaries that resulted from that feature, this BIP instead intends
670-    to leave the evaluation of BIPs to the audience.
671+[^acceptance]: **What is meant by acceptance?**
    jonatack commented at 4:42 pm on April 15, 2025:
    Per my #1819 (review) above, perhaps “adoption” would be a better term, as “acceptance” could be construed as acceptance into the BIPs repository (even if out of scope).
  44. jonatack commented at 4:44 pm on April 15, 2025: member
    ACK 2ecef94401a5175ab0c953c49a6d48884ed628e2 modulo a few comments that could be for a follow-up, along with #1819 (comment).
  45. WIP---working-on-review e0fa15fdbd


murchandamus darosior RubenSomsen jonatack real-or-random

Labels
Proposed BIP modification Process

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bips. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2025-04-19 01:10 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me