BIP3: An 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.
| #### 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.
| #### 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.
| 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.
I addressed all open feedback. Thanks @jonatack, @katesalazar, and @EthanHeilman.
| 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. |
| 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.
| 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.
| ## 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.
| * 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."
| #### 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).
| 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.
| 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.
| 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.
| 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?
| * 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.
| 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.
| #### 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.
| * A **Specification BIP** defines a set of technical rules affecting the interoperability of implementations. The | ||
| distinguishing feature of a Specification BIP is that it can be implemented, and implementations can be compliant with | ||
| it. Specification BIPs should come with or refer to a reference implementation and preferably provide test vectors. | ||
| * An **Informational BIP** describes a Bitcoin design issue, provides general guidelines or other information to the |
There was a problem hiding this comment.
| * An **Informational BIP** describes a Bitcoin design issue, provides general guidelines or other information to the | |
| * An **Informational BIP** describes a Bitcoin design issue, or provides general guidelines or other information to the |
|
|
||
| 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.
| unfocused or too broad, fail to provide proper motivation, fail to address backward compatibility where necessary, or | ||
| fail to specify the feature clearly and comprehensively. Reviewers and BIP editors should provide guidance on how the | ||
| proposal may be improved to progress toward readiness. Pull requests that are proposing off-topic or unserious ideas or | ||
| have stopped making progress may be closed. |
There was a problem hiding this comment.
| have stopped making progress may be closed. | |
| that have stopped making progress may be closed. |
| distributed discussion of ideas, but before a proposal garners some interest in the Bitcoin community, there is no need | ||
| to refer to it by a number. | ||
|
|
||
| Proposals are also not ready for number assignment if they duplicate efforts, disregard formatting rules, are too |
There was a problem hiding this comment.
A mention of or reference to the scope of BIPs described lines 45-47 would be helpful in this sentence.
|
|
||
| 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 when contacted. |
There was a problem hiding this comment.
It may be a good idea to provide a time frame here for considering when authors are non-responsive or no longer reachable.
There was a problem hiding this comment.
It may be a good idea to provide a time frame here for considering when authors are non-responsive or no longer reachable.
Good idea. By committing to a specific timeout here, authors can be informed upfront as to when their efforts will be considered abandoned. This could serve to encourage them to indicate when they will be unreachable, too.
| It occasionally becomes necessary to transfer ownership of BIPs to new owners. In general, it would be preferable to | ||
| retain the original authors of the transferred BIP, but that is up to the original authors. A good reason to transfer | ||
| ownership is because the original authors no longer have the time or interest in updating it or following through with | ||
| the BIP process, or have fallen off the face of the 'net (i.e., are unreachable or not responding to email). A bad reason |
There was a problem hiding this comment.
| the BIP process, or have fallen off the face of the 'net (i.e., are unreachable or not responding to email). A bad reason | |
| the BIP process, or are unreachable or unresponsive. A bad reason |
| 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 | ||
| manner (e.g., two weeks), the BIP editors will make a unilateral decision whether to appoint the applicants as | ||
| [Shepherds](#authors-and-shepherds) (which may be amended should the original authors make a delayed reappearance). |
There was a problem hiding this comment.
If the BIP is in draft, a new owner may be an author as well? (It would be simpler to have a single role)
|
Assigned BIP 3. |
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.