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 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 | ||
| document. They support the authors in advancing the proposal, or act as point-of-contact for the BIP in absence of the | ||
| authors. A shepherds may perform the role of an Author for any aspect of the BIP process unless overruled by an Author. |
There was a problem hiding this comment.
| authors. A shepherds may perform the role of an Author for any aspect of the BIP process unless overruled by an Author. | |
| authors. A Shepherd may perform the role of an Author for any aspect of the BIP process unless overruled by an Author. |
I'm suggesting "a Shepherd" so it matches the plurality of "an Author".
bip-update-process.md
Outdated
| ### What is the scope of the BIP repository? | ||
|
|
||
| The BIP repository is focused on information and technologies that aim to support and expand the utility of the bitcoin | ||
| currency. Related topics that are of interest to the bitcoin community may be acceptable. The scope of the BIP |
There was a problem hiding this comment.
| currency. Related topics that are of interest to the bitcoin community may be acceptable. The scope of the BIP | |
| currency. Related topics that interest the bitcoin community may be acceptable. The scope of the BIP |
There was a problem hiding this comment.
Please correct me if I’m wrong, but the original phrasing indicates that it is about relevance, whereas the proposed phrasing seems to emphasize a current action by the community. If I’m reading that right, I prefer the first.
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.
bip-update-process.md
Outdated
| ### What is the scope of the BIP repository? | ||
|
|
||
| The BIP repository is focused on information and technologies that aim to support and expand the utility of the bitcoin | ||
| currency. Related topics that are of interest to the bitcoin community may be acceptable. The scope of the BIP |
There was a problem hiding this comment.
Please correct me if I’m wrong, but the original phrasing indicates that it is about relevance, whereas the proposed phrasing seems to emphasize a current action by the community. If I’m reading that right, I prefer the first.
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.
bip-update-process.md
Outdated
| 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 BIP repository? |
There was a problem hiding this comment.
Here and throughout this document.
| ### What is the purpose of the BIP repository? | |
| ### What is the purpose of the BIPs repository? |
There was a problem hiding this comment.
I had just changed that the other way per request of @real-or-random here: murchandamus#2 (comment). How about you two discuss here? ^^
There was a problem hiding this comment.
Thinking more about this, I would say "the Bitcoin Improvement Proposal repository", not "the Bitcoin Improvement Proposals repository", so seems right to me?
There was a problem hiding this comment.
Per https://github.com/bitcoin/bips, the url and repo are named bips and the longer title is "Bitcoin Improvement Proposals". Furthermore, "proposals" in the plural form would be correct here. Thus, the comment stands.
There was a problem hiding this comment.
Okay, changed it back to "BIPs repository" throughout
There was a problem hiding this comment.
Changed it back to "BIPs repository" across the document
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
| BIPs are intended to be the primary mechanism for proposing new protocol features, coordinating client standards, and | ||
| documenting design decisions that have gone into implementations. BIPs may be submitted by anyone. |
There was a problem hiding this comment.
"primary mechanism" might be overly strong here, and might point to levels of processes that don't exist.
There was a problem hiding this comment.
Okay, I replaced it with "a means":
| BIPs are intended to be the primary mechanism for proposing new protocol features, coordinating client standards, and | |
| documenting design decisions that have gone into implementations. BIPs may be submitted by anyone. | |
| 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. |
bip-update-process.md
Outdated
| The BIP 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 was a problem hiding this comment.
I would enjoy a stronger statement here to remind unfamiliar readers that there is no organization formal or otherwise that guides bitcoin through improvement proposals or improvement deployments/implementations. Uninitiated readers may not be familiar with these more arcane matters of bitcoin development.
There was a problem hiding this comment.
It seems to me that the prior section "What is the significance of BIPs?" gets into this a bit. However, I added
| The BIP 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. | |
| The BIP 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. |
I’m open to suggestions, if you have a concrete idea how to further improve this.
bip-update-process.md
Outdated
| ## BIP Licensing | ||
|
|
||
| ### 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. | ||
|
|
There was a problem hiding this comment.
One or two sentences about the motivation behind our interest in freely licensed BIPs could be helpful to include.
There was a problem hiding this comment.
Added a couple sentences about open standards and freely licensed BIPs. As above, if you have a concrete suggestion how to improve the text, please feel free to suggest it.
bip-update-process.md
Outdated
| * 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. |
There was a problem hiding this comment.
"The idea must be of interest to the broader community or relevant to multiple software projects."
There was a problem hiding this comment.
Whether something only pertains to a single project seems orthogonal to whether a proposal is going to be adopted. Could you elaborate what action you would like me to take?
bip-update-process.md
Outdated
| #### 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. The overview is | ||
| followed by an explanation for each header. | ||
|
|
||
| ``` | ||
| BIP: <BIP number, or "?" before assignment> | ||
| * Layer: <Consensus (soft fork) | Consensus (hard fork) | Peer Services | API/RPC | Applications> |
There was a problem hiding this comment.
Given that this is intended to replace bip2, I wonder if there should be a header indicating which bip rule regime the bip was originally intended for (bip1, bip2, bip-update-process, etc).
There was a problem hiding this comment.
I don’t think that this is necessary. As there will only be one BIP Process active at the same time, and the Backward Compatibility section prescribes how preambles should be adapted with the activation of BIP3, I doubt that we would gain much.
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.
bip-update-process.md
Outdated
| 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 BIP repository? |
There was a problem hiding this comment.
Per https://github.com/bitcoin/bips, the url and repo are named bips and the longer title is "Bitcoin Improvement Proposals". Furthermore, "proposals" in the plural form would be correct here. Thus, the comment stands.
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
| * Shepherds: <Shepherds’ names and email addresses> | ||
| Status: <Draft | Complete | Deployed | Closed> | ||
| Type: <Specification | Informational | Process> | ||
| Created: <Date of number assignment, or "?" before assignment> |
There was a problem hiding this comment.
It would be clearer to keep here the date format of ISO 8601 (yyyy-mm-dd) as currently specified in BIP2.
Edit: I see that it is mentioned further below but am unsure of the utility of these duplicate sections for some of these fields. Perhaps only add duplicate sections that add useful additional information that cannot fit on one line.
There was a problem hiding this comment.
Mh, yeah, maybe these should just be folded into one rather than the current split and mix with enumerations and brief descriptions followed by longer descriptions. Will have to spend some time on thinking this through.
bip-update-process.md
Outdated
| License: <Identifier(s) of acceptable license(s)> | ||
| * License-Code: <Identifier(s) for Code under different acceptable license(s)> | ||
| * Discussion: <Mailing list thread(s), or other noteworthy discussion(s) in "date: URL" format> | ||
| * Revision: <Version number (MAJOR.MINOR.PATCH)> |
There was a problem hiding this comment.
As the Changelog lists dates/versions/descriptions and follows semver, would call this field "Version" and mention here that it follows semver.
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.
bip-update-process.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
If I'm not confused, this shouldn't pertain to Process BIPs.
There was a problem hiding this comment.
I don’t follow. What doesn’t pertain to Process BIPs?
|
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
| 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 BIP repository? |
There was a problem hiding this comment.
Changed it back to "BIPs repository" across the document
bip-update-process.md
Outdated
| The BIP 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 was a problem hiding this comment.
It seems to me that the prior section "What is the significance of BIPs?" gets into this a bit. However, I added
| The BIP 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. | |
| The BIP 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. |
I’m open to suggestions, if you have a concrete idea how to further improve this.
bip-update-process.md
Outdated
| #### 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. The overview is | ||
| followed by an explanation for each header. | ||
|
|
||
| ``` | ||
| BIP: <BIP number, or "?" before assignment> | ||
| * Layer: <Consensus (soft fork) | Consensus (hard fork) | Peer Services | API/RPC | Applications> |
There was a problem hiding this comment.
I don’t think that this is necessary. As there will only be one BIP Process active at the same time, and the Backward Compatibility section prescribes how preambles should be adapted with the activation of BIP3, I doubt that we would gain much.
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.
bip-update-process.md
Outdated
| * Shepherds: <Shepherds’ names and email addresses> | ||
| Status: <Draft | Complete | Deployed | Closed> | ||
| Type: <Specification | Informational | Process> | ||
| Created: <Date of number assignment, or "?" before assignment> |
There was a problem hiding this comment.
Mh, yeah, maybe these should just be folded into one rather than the current split and mix with enumerations and brief descriptions followed by longer descriptions. Will have to spend some time on thinking this through.
bip-update-process.md
Outdated
|
|
||
| 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 |
There was a problem hiding this comment.
I don’t follow. What doesn’t pertain to Process BIPs?
bip-update-process.md
Outdated
| ## BIP Licensing | ||
|
|
||
| ### 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. | ||
|
|
There was a problem hiding this comment.
Added a couple sentences about open standards and freely licensed BIPs. As above, if you have a concrete suggestion how to improve the text, please feel free to suggest it.
bip-update-process.md
Outdated
| * 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. |
There was a problem hiding this comment.
Whether something only pertains to a single project seems orthogonal to whether a proposal is going to be adopted. Could you elaborate what action you would like me to take?
|
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. |
|
Fixed an issue to get the checks to pass. |
bip-0003.md
Outdated
| - Deferred, Obsolete, Rejected, Replaced, and Withdrawn are gathered up into Closed.[^closed] | ||
| - Final and Active are collapsed into Deployed. | ||
| - The remaining statuses are Draft, Complete, Deployed, and Closed. | ||
| - BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection] |
There was a problem hiding this comment.
Maybe
| - BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection] | |
| - A BIP in Draft or Complete status may no longer be rejected (i.e. closed) solely on grounds of not making progress for three years.[^rejection] |
(Also update this in the PR description)
There was a problem hiding this comment.
Taken and updated in OP
There was a problem hiding this comment.
This wording is incorrect. The current text of the BIP permits movement of BIPs from Draft or Complete status to Closed by any community member, which was the exact problem shot down before.
bip-0003.md
Outdated
| 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. If the authors do not respond in a timely |
There was a problem hiding this comment.
| original authors, the BIP Editors, and the Bitcoin Development Mailing List. If the authors do not respond in a timely | |
| original authors, the BIP Editors, and the Bitcoin Development Mailing List. If the authors are unreachable or do not respond in a timely |
There was a problem hiding this comment.
Taken, but isn’t being unreachable a subset of "not responding in a timely manner"?
There was a problem hiding this comment.
I see (thanks!) By "unreachable", I wanted to mean that we don't know how to reach them.
There was a problem hiding this comment.
We should have an email address for every BIP Author, but either way it’s a fine addition
bip-0003.md
Outdated
| - Final and Active are collapsed into Deployed. | ||
| - The remaining statuses are Draft, Complete, Deployed, and Closed. | ||
| - BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection] | ||
| - A BIP may be set to Closed by its authors, or by anyone if it appears to have stopped making progress for at least a |
There was a problem hiding this comment.
Can a Complete or Deployed PR be closed, and under what conditions.
| - A BIP may be set to Closed by its authors, or by anyone if it appears to have stopped making progress for at least a | |
| - A BIP in Draft status may be set to Closed by its authors, or by anyone if it appears to have stopped making progress for at least a |
(Also update this in the PR description)
There was a problem hiding this comment.
Good suggestion. I updated the sentence in the BIP and the OP to only refer to what other people can do about closing a BIP, since BIP2 already allowed authors to close their own Draft BIPs:
- A BIP in Draft or Complete status may be updated to Closed by anyone if it appears to have stopped making progress for at least a
bip-0003.md
Outdated
| * Preamble -- Headers containing metadata about the BIP (see the section [BIP header preamble](#bip-header-preamble) | ||
| below). | ||
| * Abstract -- A short description of the technical issue being addressed. | ||
| * Motivation -- The motivation is critical for BIPs. It should clearly explain what issue the BIP addresses, and how the |
There was a problem hiding this comment.
This seems to overlap a bit with the Abstract on the previous line. Maybe emphasize more the "why" rather than the "what" (with the specification section being the "how")
There was a problem hiding this comment.
Thanks good catch. Rewrote the Motivation description.
bip-0003.md
Outdated
| existing situation is inadequate to address the problem that the BIP solves. | ||
| * 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 motivated the design and why particular |
There was a problem hiding this comment.
maybe avoid the word "motivated" here as it is also a section title
There was a problem hiding this comment.
Slightly amended this sentence.
bip-0003.md
Outdated
| ### 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. The version number is inspired by semantic versioning (MAJOR.MINOR.PATCH). |
There was a problem hiding this comment.
Suggest stipulating that entries be ordered by most recent first / descending date (i.e. like in https://keepachangelog.com/)
There was a problem hiding this comment.
Good idea. I adopted this suggestion, revisited the Changelog section, and added an example for a Changelog as well.
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
853d0eb to
d87ec4f
Compare
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
d87ec4f to
f32dbb9
Compare
There was a problem hiding this comment.
Caught up on @jonatack’s review comments. Thank you for the review. I also revisited the Description of the Preamble and the Changelog.
bip-0003.md
Outdated
| ### 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. The version number is inspired by semantic versioning (MAJOR.MINOR.PATCH). |
There was a problem hiding this comment.
Good idea. I adopted this suggestion, revisited the Changelog section, and added an example for a Changelog as well.
bip-0003.md
Outdated
| 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. If the authors do not respond in a timely |
There was a problem hiding this comment.
Taken, but isn’t being unreachable a subset of "not responding in a timely manner"?
bip-0003.md
Outdated
| - Deferred, Obsolete, Rejected, Replaced, and Withdrawn are gathered up into Closed.[^closed] | ||
| - Final and Active are collapsed into Deployed. | ||
| - The remaining statuses are Draft, Complete, Deployed, and Closed. | ||
| - BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection] |
There was a problem hiding this comment.
Taken and updated in OP
bip-0003.md
Outdated
| - Final and Active are collapsed into Deployed. | ||
| - The remaining statuses are Draft, Complete, Deployed, and Closed. | ||
| - BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection] | ||
| - A BIP may be set to Closed by its authors, or by anyone if it appears to have stopped making progress for at least a |
There was a problem hiding this comment.
Good suggestion. I updated the sentence in the BIP and the OP to only refer to what other people can do about closing a BIP, since BIP2 already allowed authors to close their own Draft BIPs:
- A BIP in Draft or Complete status may be updated to Closed by anyone if it appears to have stopped making progress for at least a
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
f32dbb9 to
1acaeb8
Compare
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
fe2be36 to
50e35d6
Compare
murchandamus
force-pushed
the
2024-12-update-bip-process
branch
from
50e35d6 to
bc9f98b
Compare
|
Here’s the diff with the changes prompted by this last round of review in the past two weeks: |
| #### 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.
Late in the process, but I'm not sure I like the word "Shepherd". If others are fine with it, don't mind me though. I would use something like "Advocate" maybe. Or maybe just let them be "Co-Authors". Is it that important to point out that they didn't contribute to the wording of the proposal? Getting it deployed is half+ the battle anyway. (I guess using "Co-Author" is a bit jarring when they are added late in the process, long after the proposal has been written.)
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.
| #### Closed[^closed] | ||
|
|
||
| A BIP that is _not in active use_, may be labeled Closed when its authors have stopped working on it, no longer | ||
| recommend the proposed approach, or no longer pursue adoption of their Complete proposal. The reason for moving the | ||
| proposal to Closed should be recorded in the Changelog section in the same commit that updates the status. |
There was a problem hiding this comment.
I agree with the reasons listed, but ultimately the authors should be the only people with the authority to close a BIP, unless the author is unresponsive for an extended period of time.
There was a problem hiding this comment.
Critically, "active use" is never defined in this BIP, and by one reading anyone/everyone is granted the authority to make the determination for themselves what active use means.
Can we please have a permanent "this BIP may or may not receive updates in the future, but should never be retired" state?
There was a problem hiding this comment.
@kallewoof: The subsections of the "Closed" section go into detail on how proposals are moved to Closed from the other states and who is eligible to do so under which circumstances. Specifically, the authors can generally move their own proposals to Closed, unless it has already been recommended to the community and other people want to proceed, or a proposal is moved to Closed because it has stopped making progress and the authors either do not wish to further pursue it or do not reply when contacted.
It seems to me that an author not responding to a personally addressed email for four weeks after not working on their proposal for a year may fit your description of "unresponsive for an extended period". If that is not the case, please let me know how this aspect of the proposal could be improved.
There was a problem hiding this comment.
@maaku: The section "Deployed" two paragraphs above describes active use as "deployed to mainnet, activated softfork, or rough consensus demonstrated". Do you have a suggestion how that description could be improved so it meets your expectation for a definition?
Would it help if I add a footnote to describe the term "active use" in more detail and reference the footnote on subsequent mentions?
There was a problem hiding this comment.
The definition here doesn't seem to entirely match the Draft->Closed and Complete->Closed conditions below, which are a bit more specific. Maybe it would be clearer to write something like:
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. 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. However, if someone volunteers to adopt the proposal within four weeks, they become the BIP's author or shepherd, and the BIP will remain Complete instead. A BIP can also be moved to Closed by the community if it has had Complete status for at least one year, here is no evidence of it being in active use, and its authors either do not object or fail to respond; unless a new author volunteers within four weeks. -
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, 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, in which case it may be reasonable to return the Closed BIP to Draft status.
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.
| #### Closed[^closed] | ||
|
|
||
| A BIP that is _not in active use_, may be labeled Closed when its authors have stopped working on it, no longer | ||
| recommend the proposed approach, or no longer pursue adoption of their Complete proposal. The reason for moving the | ||
| proposal to Closed should be recorded in the Changelog section in the same commit that updates the status. |
There was a problem hiding this comment.
@kallewoof: The subsections of the "Closed" section go into detail on how proposals are moved to Closed from the other states and who is eligible to do so under which circumstances. Specifically, the authors can generally move their own proposals to Closed, unless it has already been recommended to the community and other people want to proceed, or a proposal is moved to Closed because it has stopped making progress and the authors either do not wish to further pursue it or do not reply when contacted.
It seems to me that an author not responding to a personally addressed email for four weeks after not working on their proposal for a year may fit your description of "unresponsive for an extended period". If that is not the case, please let me know how this aspect of the proposal could be improved.
| #### Closed[^closed] | ||
|
|
||
| A BIP that is _not in active use_, may be labeled Closed when its authors have stopped working on it, no longer | ||
| recommend the proposed approach, or no longer pursue adoption of their Complete proposal. The reason for moving the | ||
| proposal to Closed should be recorded in the Changelog section in the same commit that updates the status. |
There was a problem hiding this comment.
@maaku: The section "Deployed" two paragraphs above describes active use as "deployed to mainnet, activated softfork, or rough consensus demonstrated". Do you have a suggestion how that description could be improved so it meets your expectation for a definition?
Would it help if I add a footnote to describe the term "active use" in more detail and reference the footnote on subsequent mentions?
| #### 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.
| <pre> | ||
| BIP: 3 | ||
| Title: Updated BIP Process | ||
| Author: Murch <[email protected]> |
There was a problem hiding this comment.
<[email protected]> doesn't show up when github displays the file. BIP 348, BIP 349 and BIP 379 also have this problem. Making it a code block (``` ... ```) seems to work, otherwise replacing them with < and > would be an option if this section is kept as a <pre> block.
| 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
| #### Closed[^closed] | ||
|
|
||
| A BIP that is _not in active use_, may be labeled Closed when its authors have stopped working on it, no longer | ||
| recommend the proposed approach, or no longer pursue adoption of their Complete proposal. The reason for moving the | ||
| proposal to Closed should be recorded in the Changelog section in the same commit that updates the status. |
There was a problem hiding this comment.
The definition here doesn't seem to entirely match the Draft->Closed and Complete->Closed conditions below, which are a bit more specific. Maybe it would be clearer to write something like:
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. 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. However, if someone volunteers to adopt the proposal within four weeks, they become the BIP's author or shepherd, and the BIP will remain Complete instead. A BIP can also be moved to Closed by the community if it has had Complete status for at least one year, here is no evidence of it being in active use, and its authors either do not object or fail to respond; unless a new author volunteers within four weeks. -
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, 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, in which case it may be reasonable to return the Closed BIP to Draft status.
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