BIP3: Updated BIP Process #1712
Conversation
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
2460ed1 to
47f52e5
Compare
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
47f52e5 to
9e472b8
Compare
bip-update-process.md
Outdated
| #### Authors and Shepherds | ||
|
|
||
| Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign | ||
| one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the |
There was a problem hiding this comment.
It's unclear to me why there needs to be two different roles. In several of the BIPs I have written, other BIP owners were simply added as Authors even though they did not write any of the text. This description suggest that Shepherds can approve BIP text changes in the same way Authors can. So the separation does not seem all that useful to me.
I think that having a unified "Owner" would make more sense, if people would rather not be called Author if they did not write any of the text but ostensibly are an owner of the BIP.
There was a problem hiding this comment.
The distinction can make a difference when it comes to copyright. I agree that a single role is simpler in terms of the process, but I believe this is what is implemented here. We have effectively a single Owner role (and the Owners are the union of Authors and Shepherds), but additionally an author field (which is pure metadata and doesn't have implications for the process).
Now, I agree that this is a bit difficult to explain...
Perhaps there should just be two required fields "Owners" and "Authors". This sounds like overkill because it leads to duplication. But if you think about it, I believe it's simpler than the current draft: it avoids the term Shepherd entirely, and in the text, you can easily pick the appropriate term on a case-by-case basis.
Moreover, there may be an author who is not an owner (anymore). Not sure if we'll ever need this, but there's no good reason to exclude it upfront.
There was a problem hiding this comment.
I added the additional role per the request of several reviewers. I don’t have strong feelings about this part: I would be happy with just "Owners" or "Authors", I can also live with two roles. It seems to me that people might still be discovering their positions on this aspect, so if anyone has strong feelings, please feel free to discuss further, but I’m gonna give this discussion some time to develop before making additional changes.
There was a problem hiding this comment.
I agree that a single role is simpler and would suggest a single Authors field.
There was a problem hiding this comment.
Okay, I should have addressed all open review comments. Thank you for your review, @JeremyRubin, @LarryRuane, @sipa, @EthanHeilman, and @achow101.
bip-update-process.md
Outdated
| #### Authors and Shepherds | ||
|
|
||
| Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign | ||
| one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the |
There was a problem hiding this comment.
I added the additional role per the request of several reviewers. I don’t have strong feelings about this part: I would be happy with just "Owners" or "Authors", I can also live with two roles. It seems to me that people might still be discovering their positions on this aspect, so if anyone has strong feelings, please feel free to discuss further, but I’m gonna give this discussion some time to develop before making additional changes.
There was a problem hiding this comment.
I addressed all open feedback. Thanks @jonatack, @katesalazar, and @EthanHeilman.
bip-update-process.md
Outdated
| one or more Shepherds to their BIP. Shepherds 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 point-of-contact for the BIP in absence of the | ||
| authors. Shepherds may perform the role of Authors for any aspect of the BIP process unless overruled by an Author. | ||
| Shepherds share ownership of the BIP at the discretion of the Authors. |
There was a problem hiding this comment.
Can an author revoke the shepherds?
Yes, an author can revoke Shepherds.
What if there are several authors?
I don’t think we have to litigate every possible interaction of Authors and Shepherds. If the Authors agreed to add Shepherds but then fight over the approach of the Shepherds, the involved people should figure it out. In the worst case someone should open a second BIP with the alternate approach.
The notion of herding sheep...heh :)
I was thinking about "shepherding a process", but if that first association is shared more commonly, maybe it should be "Stewards" after all.
Regarding whether or not to have a second owner role in the first place: It was requested by several BIP contributors. I don’t feel strongly about it either way. I think it’s a bit convoluted, but I see that such a role would have been used a few times in the past years.
If it need some minor clarifications, I’m happy to review suggestions, but if the addition of the Shepherds role would require several more paragraphs to litigate its scope and interactions with the Authors role, I’d prefer just dropping it altogether.
|
Thanks for adding Sheperd, I think it's good enough as written and the name is fine. Rose by any other name would smell just as sweet. The only other alternative I could think of would be to make Author a newly optional field, and have a new field (e.g., Proposers) be the sub-in for the current meaning of author. This would also serve to separate authorship and champion-ship cleanly. But that's more confusing and a more major change. So I think Sheperd solves the problem. |
bip-update-process.md
Outdated
| community. The BIP process as defined by BIP 2 aimed to facilitate the design and | ||
| activation of protocol changes. In the past years, BIPs have more often described interoperational standards beyond the base | ||
| protocol. The community has debated repeatedly about the role of the BIP Editors, and aspects of the process | ||
| specified by BIP 2 that did not seem to achieve the intended goals. This BIP sunsets aspects of the BIP 2 process |
There was a problem hiding this comment.
Suggest keeping only the last sentence of this paragraph.
Also, as mentioned in #1712 (comment), we are seeing quite a few new BIPs for protocol changes nowadays.
There was a problem hiding this comment.
I think I get the confusion now. I meant "more often than before", not "more often than not". I have restated what I wanted to convey here.
There was a problem hiding this comment.
I revisited this comment and trimmed the Motivation further.
bip-update-process.md
Outdated
| one or more Shepherds to their BIP. Shepherds 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 point-of-contact for the BIP in absence of the | ||
| authors. Shepherds may perform the role of Authors for any aspect of the BIP process unless overruled by an Author. | ||
| Shepherds share ownership of the BIP at the discretion of the Authors. |
There was a problem hiding this comment.
...I’d prefer just dropping it altogether.
I'd drop it for now in the name of simplicity, which I believe is also a primary goal of this BIP.
bip-update-process.md
Outdated
| Authors: <Authors’ names and email addresses> | ||
| * Shepherds: <Shepherds’ names and email addresses> | ||
| Status: <Draft | Complete | Deployed | Closed> | ||
| Type: <Specification | Informational | Process> |
There was a problem hiding this comment.
This line replaces "Standards Track" with "Specification". However, "Specification" is also a section in the list above that is frequently present in BIPs. It would seem both clearer and (much) simpler to leave "Standards Track" unchanged, unless there is a very compelling reason to change it?
There was a problem hiding this comment.
As you probably remember, there seems to be irreconcilable disagreement among BIP Editors what constitutes a "standard". Given that there are also numerous BIPs that are currently mislabeled as "Informational" while containing a technical specification that implementation can be in compliance with, it seems cleaner to introduce a new Type as a means to mend both of these issues.
I could live with applying a new definition to the existing Standards Track Type, and relabeling existing BIPs should BIP3 be adopted, but I would consider it a failure if retaining the old Type led to lots of technical specifications remaining mislabeled as Informational.
There was a problem hiding this comment.
I could live with applying a new definition to the existing Standards Track Type, and relabeling existing BIPs
Understood. I think I mildly prefer this to avoid conflating the Specification type with Specification sections.
bip-update-process.md
Outdated
| #### Authors and Shepherds | ||
|
|
||
| Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign | ||
| one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the |
There was a problem hiding this comment.
I agree that a single role is simpler and would suggest a single Authors field.
|
Assigned BIP 3. |
There was a problem hiding this comment.
I’ve addressed most of the review comments. I’m doing another pass, and taking a closer look on how to amend the specification of the Preamble, what to do about the Shepherd role, whether to stick to Standards Track or switch to Specification Type, and whether to use version instead of Revision.
Thank you for the number assignment and review, @jonatack and @kanzure.
bip-update-process.md
Outdated
| Authors: <Authors’ names and email addresses> | ||
| * Shepherds: <Shepherds’ names and email addresses> | ||
| Status: <Draft | Complete | Deployed | Closed> | ||
| Type: <Specification | Informational | Process> |
There was a problem hiding this comment.
As you probably remember, there seems to be irreconcilable disagreement among BIP Editors what constitutes a "standard". Given that there are also numerous BIPs that are currently mislabeled as "Informational" while containing a technical specification that implementation can be in compliance with, it seems cleaner to introduce a new Type as a means to mend both of these issues.
I could live with applying a new definition to the existing Standards Track Type, and relabeling existing BIPs should BIP3 be adopted, but I would consider it a failure if retaining the old Type led to lots of technical specifications remaining mislabeled as Informational.
|
I have renamed the "Revision" header to "Version" and deduplicated the description of the Preamble headers. At this time, I’m sticking to keeping the Shepherd role and the introduction of the Specification BIP type. |
There was a problem hiding this comment.
Hey @kallewoof and @maaku, thanks for taking a look. I have responded to your comments, please let me know what you think.
bip-0003.md
Outdated
| #### Authors and Shepherds | ||
|
|
||
| Authors may want additional help with the BIP process after writing an initial draft. In that case, they may assign | ||
| one or more Shepherds to their BIP. Shepherds 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. Shepherds may perform the role of Authors for any aspect of the BIP process unless overruled by an Author. | ||
| Shepherds share ownership of the BIP at the discretion of the Authors. | ||
|
|
There was a problem hiding this comment.
Hi @kallewoof, this secondary owner role has gone through multiple iterations, first called "Proponent", then "Shepherd", after also considering "Advocates", "Champions", "Stewards", and "Proposers".
Several people explicitly requested a secondary Owner role, multiple reviewers prefer a single Owner role. Every term that was considered for the role has been found wanting by some reviewers. If you have a suggestion on how to progress from that point, I’m all ears.
| Created: 2025-01-09 | ||
| License: BSD-2-Clause | ||
| Post-History: https://github.com/murchandamus/bips/pull/2 | ||
| https://gnusha.org/pi/bitcoindev/[email protected]/#t |
There was a problem hiding this comment.
These links (Post-History and Comments-URI) aren't rendered as clickable, which seems a little lame; and changing <pre> to a code block doesn't help here. Would it make sense to move this out of the header into its own section (perhaps near the "Changelog" section? or "Related Works" or "Acknowledgements" though neither are specified here) looking something like:
## Discussion
* 2024-05-14 https://github.com/murchandamus/bips/pull/2
* 2024-04-02 https://gnusha.org/pi/bitcoindev/[email protected]/#t
There was a problem hiding this comment.
I prefer for the discussion links to be in the preamble, as it’s accessible and having a section for it would feel like overkill, but I do agree that it would be nice for them to be rendered as links. Perhaps we can exempt just the URLs from code formatting in the preamble?
There was a problem hiding this comment.
Given that the email address doesn’t get rendered presumably because it was interpreted as HTML, I tried to use HTML to define the URLs as links which seems to work.
There was a problem hiding this comment.
I thought having a section was appealing both because it encourages you to read the current proposal first before diving into the history, and, for proposals with a lot of discussion, makes it easier to include all that discussion without being a huge upfront distraction.
Maybe depends a bit on whether you view the link as helping with process alignment ("Did they post to the list before requesting a BIP number? Yes? Great!") or as further background information for readers/implementors ("What was the thought process behind this?"). eg BIP 340 has a link to the original announcement as per process requirements, but doesn't have a link to the additional discussion from 2019-05-06 (see BIP 341) that resulted in the pubkeys being 32 bytes instead of 33 bytes. I think having links in the preamble/header encourages minimising them, while having a section later in the document would encourage providing more info; the latter seems like it would be more useful to me, but YMMV.
Doing html markup manually feels like it would just make the source document harder to read/write; probably better to just copy&paste the url in that case; it's not really that big of a deal.
There was a problem hiding this comment.
Thanks for elaborating, I see where you are coming from.
There was a problem hiding this comment.
I have considered this further, and have decided to retain the Discussion header over a Discussion section. While the argument that a first-time reader may first skim the BIP before taking a look at Discussions linked to in the section sounds compelling, for power users of the repository such as BIP Editors and other frequent contributors to the process having the links in the Preamble represents a significant accessibility improvement.
There was a problem hiding this comment.
@ajtowns: Do you think it would be worth mentioning an optional "References" section that authors can use to link to related reading material?
There was a problem hiding this comment.
There are 37 bips that have that section (compared to 29 that have a Post-History header), so it could be worthwhile to document it. BIP 8 links to its mailing list discussion via its References section rather than having a Post-History header. However, if you want to encourage links to prior discussion of the bip to be in the header, might be better to not document the References section, authors who want to add further references can probably figure out how to add a section for it without much handholding?
|
Thanks @ajtowns, I took your suggestions for improving the Closed section and continue to look into the non-rendering email addresses. |
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
2 times, most recently
from
6369aae to
f4955a5
Compare
There was a problem hiding this comment.
I’ve addressed most of @jonatack’s feedback, trimmed the Motivation section, fixed the capitalization in internal links, use four weeks as the reaction time throughout, and clarified which sections are mandatory.
I have decided not to introduce a distinction between "Closed after Deployed" and "Closed before ever Deployed" as someone suggested. I did add two more Licenses that were requested by Reviewers to the Acceptable Licenses.
I am working on a reply to @maaku’s concern.
bip-update-process.md
Outdated
| community. The BIP process as defined by BIP 2 aimed to facilitate the design and | ||
| activation of protocol changes. In the past years, BIPs have more often described interoperational standards beyond the base | ||
| protocol. The community has debated repeatedly about the role of the BIP Editors, and aspects of the process | ||
| specified by BIP 2 that did not seem to achieve the intended goals. This BIP sunsets aspects of the BIP 2 process |
There was a problem hiding this comment.
I revisited this comment and trimmed the Motivation further.
|
I replied to @maaku here: #1712 (comment) As far as I am aware, I am caught up to all review comments, except whether to replace the "Discussion" header with a Discussion section. Please let me know if I am missing anything else. |
There was a problem hiding this comment.
After receiving feedback and further discussing the purpose and characteristics of the various Statuses, I have made the following changes:
- Clarify that Closed BIPs are retained and not deleted
- Permit BIPs to remain in the Complete Status indefinitely
- Replace the "Superseded-By" header with "Proposed-Replacement"
- Update description of "Replaces" header
- Clarify updates to BIPs should BIP3 be adopted
| Created: 2025-01-09 | ||
| License: BSD-2-Clause | ||
| Post-History: https://github.com/murchandamus/bips/pull/2 | ||
| https://gnusha.org/pi/bitcoindev/[email protected]/#t |
There was a problem hiding this comment.
I have considered this further, and have decided to retain the Discussion header over a Discussion section. While the argument that a first-time reader may first skim the BIP before taking a look at Discussions linked to in the section sounds compelling, for power users of the repository such as BIP Editors and other frequent contributors to the process having the links in the Preamble represents a significant accessibility improvement.
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
6cbd8f6 to
fdc8048
Compare
|
Since this PR is only marking this process as "draft" rather than making it the new way of doing BIPs, and can be updated later, is there any reason not to merge this PR? Followup PRs to further improve the text and perhaps to replace BIP 2 can be opened and argued about at that point? |
There was a problem hiding this comment.
Concept ACK to updating the BIP Process, particularly to simplify things like statuses and tracks. I haven't read through all the discussions but this seems reasonable, and assuming it meets criteria for being BIP-able, I see no reason why this shouldn't be merged as a draft proposal.
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
4de0d0a to
c34ab2c
Compare
|
LGTM. I have provided some feedback out of band, which has been addressed. It's not clear to me what the procedure should be for actually adopting these changes herein, but I don't see why it wouldn't be ready for merging as a Draft. |
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
c34ab2c to
d5c189f
Compare
|
ACK d5c189f draft appears complete, latest push is squash-only, further improvements can be made on the road to upgrading to Proposed status |
| Created: 2025-01-09 | ||
| License: BSD-2-Clause | ||
| Post-History: https://github.com/murchandamus/bips/pull/2 | ||
| https://gnusha.org/pi/bitcoindev/[email protected]/#t |
There was a problem hiding this comment.
@ajtowns: Do you think it would be worth mentioning an optional "References" section that authors can use to link to related reading material?
BIP3: Address follow-ups from #1712
There was a problem hiding this comment.
I think this BIP is well-written and a much-needed improvement over BIP2. None of my review comments are show-stoppers to me, so I can say without reservation that I support BIP3.
The distinction between what is and isn't on-topic still seems tricky. I think it's probably a good thing that the BIP gives some loose guidance without trying to pin it down too precisely as it will probably always remain a bit of a judgement call.
A related issue is the dependence on the bitcoindev mailing list as the sole means of progressing BIPs. While generally this hasn't been an issue, it could theoretically be the case that the moderation policy of the mailing list conflicts with that of the BIP editors. That said, I think specifying contingencies for this in the BIP is premature. We'll just have to deal with such cases as they emerge.
| 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 |
There was a problem hiding this comment.
The footnote is connected to "acceptance" but then only talks about "adoption". The difference between these two (if any) is currently not clear to me.
There was a problem hiding this comment.
I think of "acceptance" as whether the community supports conceptually moving forward on a BIP, and of adoption as the progress toward implementations deploying support.
|
|
||
| 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 |
There was a problem hiding this comment.
Here the word "acceptance" is slightly confusing. It can also be misread to mean "accepting a proposal as a BIP" (for which we do have sort of an informal decision body) rather than "the community actively starts using the proposal".
There was a problem hiding this comment.
I rewrote that sentence and replaced the footnote with two mostly new footnotes on adoption and acceptance
| 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. |
There was a problem hiding this comment.
I understand why this last sentence was added, but it seems like secondary information that is not integral to the core question of the paragraph and may be more suited for a footnote.
There was a problem hiding this comment.
Moved the last sentence to the footnote
There was a problem hiding this comment.
Hey Ruben, thanks for the review, sorry for the slow turn-around. I addressed your comments in #1819.
| 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 |
There was a problem hiding this comment.
I think of "acceptance" as whether the community supports conceptually moving forward on a BIP, and of adoption as the progress toward implementations deploying support.
| 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. |
There was a problem hiding this comment.
Moved the last sentence to the footnote
|
|
||
| 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 |
There was a problem hiding this comment.
I rewrote that sentence and replaced the footnote with two mostly new footnotes on adoption and acceptance
| * 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 |
There was a problem hiding this comment.
I thought about this back and forth quite a bit, but in the end my thinking is that the problem only exists on the side of the original BIP:
It is on the original BIP where things get complicated. The BIP is an author document, but depending on its progress it may be partially owned by community as well. Who gets to decide whether the original document should endorse a potential replacement? 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 this manner. As it is freshly written, it is wholly owned by its authors, there is no community ownership, and the original BIP’s authors have no privileged role regarding the new BIP. Therefore, the authors of the new BIP can unilaterally recommend that it should be considered a replacement for a prior BIP. From there, the community can then evaluate the proposal and adopts or reject it, thus establishing whether it is successful in superseding the original or not.
|
If anyone else has review comments for BIP 3, please leave them on the latest version in the open pull request |
This Bitcoin Improvement Proposal (BIP) proposes new guidelines for the preparation of BIPs and policies relating to the publication of BIPs. If adopted, it would replace BIP 2.
From the BIP:
Changes from BIP 2
Workflow
BIP Format
Preamble