BIP3: Updated BIP Process

murchandamus commented at 9:52 pm on December 10, 2024: contributor

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

Status field values are reduced from nine to four:
- Deferred, Obsolete, Rejected, Replaced, and Withdrawn are gathered up into Closed.
- Final and Active are collapsed into Deployed.
- Proposed is renamed to Complete.
- The remaining statuses are Draft, Complete, Deployed, and Closed.
A BIP in Draft or Complete status may no longer be closed solely on grounds of not making progress for three years.
- A BIP in Draft status may be set to Closed by anyone if it appears to have stopped making progress for at least a year and its authors do not assert that they are still working on it when contacted.
- Complete BIPs can only be moved to Closed by its authors and may remain in Complete indefinitely.
A BIP in Draft or Complete status may no longer be closed solely on grounds of not making progress for three years.
A BIP in Draft status may be set to Closed by anyone if it appears to have stopped making progress for at least a year and its authors do not assert that they are still working on it when contacted.
Process BIPs are living documents that do not ossify and may be modified indefinitely.
Some judgment calls previously required from BIP Editors are reassigned either to the BIP authors or the repository’s audience.
The comment system is abolished.

BIP Format

The Standards Track type is superseded by the similar Specification type.
Many sections are declared optional, it is up to the authors and audience to judge whether all relevant topics have been comprehensively addressed and which topics require a designated section to do so.
“Other Implementations” sections are discouraged.
Auxiliary files are only permitted in the corresponding BIP’s subdirectory, as no one used the alternative of labeling them with the BIP number.
Tracking of adoption, acceptance, and community consensus is out of scope for the BIPs repository, except to determine whether a BIP is in active use for the move into or out of the Deployed status.
The distinction between recommended and acceptable licenses was dropped.
Most licenses that have not been used in the BIP process have been dropped from the list of acceptable licenses.

Preamble

Comments-URI and Comment-Summary headers are dropped from the preamble.
The “Superseded-By” header is replaced with the “Proposed-Replacement” header.
The “Post-History” header is replaced with the “Discussion” header.
The “Discussions-To” header is dropped as it has never been used in any BIP.
Introduce Deputies and optional Deputies header.
Titles may now be up to 50 characters.
Layer header is optional for Specification BIPs or Informational BIPs, as it does not make sense for all BIPs.
Rename “Author” field to “Authors”.

murchandamus renamed this:
~~Draft an updated BIP Process~~
An updated BIP Process
on Dec 10, 2024

murchandamus force-pushed on Dec 10, 2024

in bip-update-process.md:55 in 47f52e594f outdated

50+#### Authors and Shepherds
51+
52+Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign
53+one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the
54+document. They support the authors in advancing the proposal, or act as point-of-contact for the BIP in absence of the
55+authors. A shepherds may perform the role of an Author for any aspect of the BIP process unless overruled by an Author.

JeremyRubin commented at 3:56 pm on December 11, 2024:

s/A shepherds/Shepherds/

LarryRuane commented at 7:12 pm on December 11, 2024:

0authors. 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”.

murchandamus commented at 7:27 pm on December 11, 2024:

Thanks, will fix that. As one of the people that were suggesting the addition of this secondary owner role, what do you think about the description of it?

JeremyRubin commented at 0:21 am on December 12, 2024:

sounds good to me.

murchandamus commented at 0:43 am on December 12, 2024:

Great, thanks

in bip-update-process.md:29 in 47f52e594f outdated

24+community. The BIP process as defined by BIP 2 thus far seems to have been fashioned to facilitate the design and
25+activation of protocol changes. In the past years, BIPs more often describe interoperable features beyond the base
26+protocol. The community has had multiple debates about the role of BIP Editors, and some aspects of the process
27+specified by BIP 2 that did not seem to achieve the intended goals. This proposal sunsets aspects of the BIP 2 process
28+that did not achieve broad adoption, reduces the judgment calls assigned to the BIP Editor role, and delineates the
29+BIP Types more expediently.

sipa commented at 5:46 pm on December 11, 2024:

“expediently” seems strange to me here. What about “explicitly” or “clearly”?

murchandamus commented at 6:18 pm on December 17, 2024:

Changed to “clearly”

in bip-update-process.md:69 in 47f52e594f outdated

64+
65+### What is the purpose of the BIP repository?
66+
67+The [BIP repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals.
68+Through its high visibility, it facilitates the community-wide consideration of BIPs and provides a well-established
69+source to retrieve the latest version of any BIP. The repository records all changes to each BIP transparently and

LarryRuane commented at 7:14 pm on December 11, 2024:

0source to retrieve the latest version of any BIP. The repository transparently records all changes to each BIP and

in bip-update-process.md:70 in 47f52e594f outdated

65+### What is the purpose of the BIP repository?
66+
67+The [BIP repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals.
68+Through its high visibility, it facilitates the community-wide consideration of BIPs and provides a well-established
69+source to retrieve the latest version of any BIP. The repository records all changes to each BIP transparently and
70+allows any community member to easily retain a complete copy of the archive.

LarryRuane commented at 7:15 pm on December 11, 2024:

0allows any community member to retain a complete copy of the archive easily.

in bip-update-process.md:86 in 47f52e594f outdated

81+
82+## BIP format and structure
83+
84+### Specification
85+
86+BIPs should be written in mediawiki or markdown[^markdown] format.

LarryRuane commented at 7:16 pm on December 11, 2024:

0BIPs should be written in MediaWiki or markdown[^markdown] format.

in bip-update-process.md:101 in 47f52e594f outdated

 96+* Specification -- The technical specification should describe the syntax and semantics of any new feature. The
 97+  specification should be detailed enough to enable any bitcoin project to create an interoperable implementation.
 98+* Rationale -- The rationale fleshes out the specification by describing what motivated the design and why particular
 99+  design decisions were made. It should describe related work and alternate designs that were considered. The rationale
100+  should record relevant objections or important concerns that were raised and addressed as this proposal was developed.
101+* Backward compatibility -- A section describing any backwards incompatibilities, their severity, and instructions how

LarryRuane commented at 7:17 pm on December 11, 2024:

0* Backward compatibility -- A section describing any backward incompatibilities, their severity, and instructions on how

in bip-update-process.md:149 in 47f52e594f outdated

144+    Random J. User <address@dom.ain>
145+
146+If there are multiple authors, each should be on a separate line following [RFC
147+2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions.
148+
149+__Shepherds__: The Shepherds header lists additional owners of the BIP. Shepherds stand-in for the original authors of a

LarryRuane commented at 7:20 pm on December 11, 2024:

0__Shepherds__: The Shepherds header lists additional owners of the BIP. Shepherds stand in for the original authors of a

jonatack commented at 11:20 pm on January 7, 2025:

Larry is correct here: the verb is “to stand in” without a hyphen. That said, suggest dropping the shepherds.

in bip-update-process.md:167 in 47f52e594f outdated

162+See the [BIP Licensing](#bip-licensing) section below for a description of the acceptable Licenses and their SPDX
163+License Identifiers.
164+
165+If there are multiple licenses, each should be on a separate line.
166+
167+__Discussion__: The Discussion header is used to point the audience to relevant discussions of the BIP, e.g. the mailing

LarryRuane commented at 7:20 pm on December 11, 2024:

0__Discussion__: The Discussion header is used to point the audience to relevant discussions of the BIP, e.g., the mailing

in bip-update-process.md:180 in 47f52e594f outdated

175+is provided as MAJOR.MINOR.PATCH, e.g. `Revision: 2.3.1`.
176+
177+__Requires__: BIPs may have a Requires header to indicate existing BIPs the new proposal depends on. If multiple BIPs
178+are required, they should be listed in one line separated by a comma and space (e.g. "1, 2").
179+
180+__Replaces/Superseded-By__: BIPs may have a Replaces header that contains the number of an older BIP it renders

LarryRuane commented at 7:22 pm on December 11, 2024:

0__Replaces/Superseded-By__: BIPs may have a Replaces header that contains the number of an older BIP that it renders

in bip-update-process.md:181 in 47f52e594f outdated

176+
177+__Requires__: BIPs may have a Requires header to indicate existing BIPs the new proposal depends on. If multiple BIPs
178+are required, they should be listed in one line separated by a comma and space (e.g. "1, 2").
179+
180+__Replaces/Superseded-By__: BIPs may have a Replaces header that contains the number of an older BIP it renders
181+obsolete. A Superseded-By header indicates in turn that a BIP has been rendered obsolete by the later document with the

LarryRuane commented at 7:22 pm on December 11, 2024:

0obsolete. A Superseded-By header indicates, in turn, that a BIP has been rendered obsolete by the later document with the

murchandamus force-pushed on Dec 11, 2024

in bip-update-process.md:78 in 9e472b8877 outdated

73+providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.
74+
75+### What is the scope of the BIP repository?
76+
77+The BIP repository is focused on information and technologies that aim to support and expand the utility of the bitcoin
78+currency. Related topics that are of interest to the bitcoin community may be acceptable. The scope of the BIP

LarryRuane commented at 7:31 pm on December 11, 2024:

0currency. Related topics that interest the bitcoin community may be acceptable. The scope of the BIP

murchandamus commented at 6:27 pm on December 17, 2024:

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.

in bip-update-process.md:213 in 9e472b8877 outdated

208+![Status Diagram](bip-update-process/status-diagram.png "Status Diagram for the BIP Workflow")
209+
210+### Ideation
211+
212+After having an idea, the authors should evaluate whether it meets the criteria to become a BIP, as described in this
213+BIP. The idea must be of interest to the broader community or relevant to multiple software projects. Small improvements

LarryRuane commented at 7:32 pm on December 11, 2024:

0BIP. The idea must interest the broader community or be relevant to multiple software projects. Minor improvements

murchandamus commented at 6:34 pm on December 17, 2024:

As above, I prefer “be of interest” over “interest”. I took “Minor” over “Small”

in bip-update-process.md:215 in 9e472b8877 outdated

210+### Ideation
211+
212+After having an idea, the authors should evaluate whether it meets the criteria to become a BIP, as described in this
213+BIP. The idea must be of interest to the broader community or relevant to multiple software projects. Small improvements
214+and matters concerning only a single project usually do not require standardization and should instead be brought up to
215+the relevant project directly.

LarryRuane commented at 7:42 pm on December 11, 2024:

0and matters concerning only a single project usually do not require standardization and should be brought up directly to
1the relevant project.

murchandamus commented at 6:37 pm on December 17, 2024:

“Instead” is meant to emphasize that such an issue would not be relevant, but I moved the “directly”.

in bip-update-process.md:218 in 9e472b8877 outdated

213+BIP. The idea must be of interest to the broader community or relevant to multiple software projects. Small improvements
214+and matters concerning only a single project usually do not require standardization and should instead be brought up to
215+the relevant project directly.
216+
217+The authors should first research whether an idea has been considered before. Ideas in bitcoin are often rediscovered,
218+and prior related discussions may inform the authors what issues may arise in its progression. After some investigation,

LarryRuane commented at 7:44 pm on December 11, 2024:

0and prior related discussions may inform the authors of the issues that may arise in its progression. After some investigation,

in bip-update-process.md:219 in 9e472b8877 outdated

214+and matters concerning only a single project usually do not require standardization and should instead be brought up to
215+the relevant project directly.
216+
217+The authors should first research whether an idea has been considered before. Ideas in bitcoin are often rediscovered,
218+and prior related discussions may inform the authors what issues may arise in its progression. After some investigation,
219+the novelty of an idea can be tested by posting about it to the [Bitcoin Development Mailing

LarryRuane commented at 7:45 pm on December 11, 2024:

0the novelty of an idea can be tested by posting on the [Bitcoin Development Mailing

in bip-update-process.md:223 in 9e472b8877 outdated

218+and prior related discussions may inform the authors what issues may arise in its progression. After some investigation,
219+the novelty of an idea can be tested by posting about it to the [Bitcoin Development Mailing
220+List](https://groups.google.com/g/bitcoindev). Prior correspondence can be found in the [mailing list
221+archive](https://gnusha.org/pi/bitcoindev/).
222+
223+Vetting an idea publicly before investing the time to formally describe the idea is meant to save both the authors and

LarryRuane commented at 7:47 pm on December 11, 2024:

0Vetting an idea publicly before investing the time to describe the idea formally is meant to save both the authors and

in bip-update-process.md:227 in 9e472b8877 outdated

222+
223+Vetting an idea publicly before investing the time to formally describe the idea is meant to save both the authors and
224+the broader community time. Not only may someone point out relevant discussion topics that were missed in the authors’
225+research, or that an idea is guaranteed to be rejected based on prior discussions, but describing an idea publicly also
226+tests whether it is of interest to more people besides the authors. After establishing that the idea may be of interest
227+to the bitcoin community, the authors should work on drafting a BIP.

LarryRuane commented at 7:50 pm on December 11, 2024:

0tests whether it is of interest to more people besides the authors. After establishing that the idea may interest
1the bitcoin community, the authors should work on drafting a BIP.

sipa commented at 8:24 pm on December 11, 2024:

Should “Bitcoin community” not be capitalized?

murchandamus commented at 6:40 pm on December 17, 2024:

See above

murchandamus commented at 7:55 pm on December 17, 2024:

After changing everything to lowercase at behest of some earlier review, and now getting two comments requesting capitalization, I decided to go with what I have been doing for the last decade: Capitalize the abstract idea, network and system “Bitcoin”, lowercase the unit of the currency.

in bip-update-process.md:343 in 9e472b8877 outdated

338+obvious that the new attempt directly continues work on the same idea, in which case it may be reasonable to return the
339+Closed BIP to Draft status.
340+
341+### Changelog
342+
343+To help implementers understand updates to a BIP, any changes after it has reached Complete are tracked with version,

sipa commented at 8:42 pm on December 11, 2024:

If I read this section correctly, version numbers start at 1.0.0 (at promotion to complete), and changes/versions are not tracked before that point.

Would it make sense to allow/encourage (but not mandate) 0.x.y version numbers/changelog in the draft phase? For example BIP 327 has a significant, and useful, pre-Final version history today.

murchandamus commented at 7:45 pm on December 17, 2024:

Thanks, that’s a good clarification, I’ve made changes to this paragraph to permit the Changelog during the Draft phase and to explicitly require it after Complete has been reached.

in bip-update-process.md:37 in 9e472b8877 outdated

32+
33+### What is a BIP?
34+
35+BIPs cover the range of interests of the bitcoin community. The main topic is technology that supports the bitcoin
36+currency. Most BIPs provide a concise, self-contained, technical description of one new concept, feature, or standard.
37+Some BIPs describe processes, implementation guidelines, best practices, incident reports (e.g.

sipa commented at 8:44 pm on December 11, 2024:

μnit: comma after e.g. and i.e.

murchandamus commented at 6:21 pm on December 17, 2024:

TIL

sipa commented at 8:52 pm on December 11, 2024: member

This looks great. Just a few nits.

in bip-update-process.md:47 in 9e472b8877 outdated

42+documenting design decisions that have gone into implementations. BIPs may be submitted by anyone.
43+
44+### BIP Ownership
45+
46+Each BIP is primarily owned by its authors and represents the authors’ opinion or recommendation. The authors are
47+expected to foster discussion, address feedback and dissenting opinions, and, if applicable, advance the adoption of

EthanHeilman commented at 1:52 am on December 12, 2024:

To what degree do we want the BIP PR request to be the place where discussion about a BIP happens vs the mailinglist? Is it appropriate to suggest alternative designs in the PR comments?

murchandamus commented at 8:18 pm on December 17, 2024:

I am not sure that there is a clear line here. I’d say conceptual review and approach discussion should happen preferably in response to the initial presentation of the new idea, but it may still be on-topic in the pull request. If it requires a complete overhaul, it may be better to bring it to the mailing list, as an alternate design that requires a complete rewrite might not be actionable in the context of a pull request.

Do you think there is something missing here that should be clarified? Do you have a concrete suggestion?

EthanHeilman commented at 10:46 pm on December 17, 2024:

You answered my question. I wasn’t sure if this BIP was attempting provide a concrete position of type of feedback. That had been the case I would’ve recommend stating what is allowed more explicitly. However given that it isn’t the case, it is reasonable as written.

in bip-update-process.md:53 in 9e472b8877 outdated

48+their proposal within the bitcoin community.
49+
50+#### Authors and Shepherds
51+
52+Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign
53+one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the

achow101 commented at 10:57 pm on December 16, 2024:

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.

real-or-random commented at 9:03 am on December 17, 2024:

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.

murchandamus commented at 8:20 pm on December 17, 2024:

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.

jonatack commented at 11:22 pm on January 7, 2025:

I agree that a single role is simpler and would suggest a single Authors field.

in bip-update-process.md:123 in 9e472b8877 outdated

118+  Title: <BIP title (≤ 50 characters)>
119+  Authors: <Authors’ names and email addresses>
120+* Shepherds: <Shepherds’ names and email addresses>
121+  Status: <Draft | Complete | Deployed | Closed>
122+  Type: <Specification | Informational | Process>
123+  Created: <Date of number assignment (yyyy-mm-dd)>

achow101 commented at 11:06 pm on December 16, 2024:

Perhaps should also say ‘or “?” before assignment’ as otherwise I think people will just put whatever date they began writing the document (this is typically what I do).

murchandamus commented at 6:32 pm on December 17, 2024:

Good point, thanks.

in bip-update-process.md:147 in 9e472b8877 outdated

142+format of each authors header value must be
143+
144+    Random J. User <address@dom.ain>
145+
146+If there are multiple authors, each should be on a separate line following [RFC
147+2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions.

achow101 commented at 11:15 pm on December 16, 2024:

AFAICT RFC 2822 doesn’t specify “continuation line conventions” with that phrasing. The word “continuation” only appears once in a footnote. Perhaps it should refer to the Long Header Fields section? Otherwise, it’s not entirely clear what the convention actually is, and whether that section describes the convention.

This sentence appears to be lifted from PEP 1, which provides equally vague guidance.

murchandamus commented at 8:10 pm on December 17, 2024:

Okay good, I replaced it with

0-If there are multiple authors, each should be on a separate line following [RFC
1-2822](https://datatracker.ietf.org/doc/html/rfc2822.html) continuation line conventions.
2+Multiple authors should be recorded on separate lines:
3+
4+    Authors: Random J. User <address@dom.ain>
5+             Anata Sample <anata@domain.example>

in bip-update-process.md:246 in 9e472b8877 outdated

241+
242+#### Draft
243+
244+After fleshing out the proposal further and ensuring that it is of high quality and properly formatted, the authors
245+should open a pull request to the [BIP repository](https://github.com/bitcoin/bips). The document must adhere to the
246+formatting requirements specified below and should be provided as a file named with a working title of the form

achow101 commented at 11:20 pm on December 16, 2024:

Formatting requirements are specified above.

in bip-update-process.md:261 in 9e472b8877 outdated

256+
257+Proposals are also not ready for number assignment if they duplicate efforts, disregard formatting rules, are too
258+unfocused or too broad, fail to provide proper motivation, fail to address backwards compatibility where necessary, or
259+fail to specify the feature clearly and comprehensively. Reviewers and BIP editors should provide guidance on how the
260+proposal may be improved to progress toward readiness. Pull requests that are proposing off-topic or unserious ideas or
261+have stopped to make progress may be closed.

achow101 commented at 11:22 pm on December 16, 2024:

“have stopped to make progress” reads weirdly to me. Perhaps “have stopped making progress”.

in bip-update-process.md:656 in 9e472b8877 outdated

651+    writing a new process document every time new situations arise, it seems preferable to allow the process to adapt to
652+    the concerns of the future in specific aspects. Therefore, Process BIPs are defined as living documents that remain
653+    open to amendment. If a Process BIP requires large modifications or even a complete overhaul, a new BIP should be
654+    preferred.
655+[^new-BIP]: **Why should the specification of an implemented BIP no longer be changed?**  
656+    After a Complete or Deployed BIP have been deployed by one or more implementations, breaking changes to the

achow101 commented at 11:25 pm on December 16, 2024:

s/have/has

in bip-update-process.md:494 in 9e472b8877 outdated

489+
490+A BIP editor will:
491+
492+* Assign a BIP number and BIP type in the pull request
493+* Merge the pull request when it is ready
494+* List the BIP in the [README](README.mediawiki)

achow101 commented at 11:37 pm on December 16, 2024:

Updating the README has been done by BIP authors in their PRs to add their BIP. Changing to having the BIP editors do this requires either the BIP editors make another PR or the BIP author allows Editors to modify their PR. I find either option to be undesirable. Also, the former would break CI.

Instead, I think this should be in the list above as something for the editors to check has been done correctly.

murchandamus commented at 6:46 pm on December 17, 2024:

Good point, thanks. I think so far it has been a mix, sometimes the BIP Editors added a commit to the pull request to list the BIP in the Readme, sometimes the authors do it. I changed it to “Ensure that the BIP is listed in the README” and put the line about merging last.

in bip-update-process.md:506 in 9e472b8877 outdated

501+original intent of the authors. Such a change must be recorded in the Changelog if it’s noteworthy per the criteria
502+mentioned in the [Changelog](#changelog) section.
503+
504+## Backward Compatibility
505+
506+### Changes from BIP 2

achow101 commented at 11:41 pm on December 16, 2024:

Another change is the definition of the Created header.

murchandamus commented at 6:48 pm on December 17, 2024:

No, BIP2 already defined the Created header as the date the number was assigned, this was just not consistently implemented.

See BIP 2:

murchandamus commented at 7:01 pm on December 17, 2024: contributor

I have addressed the minor items from review, will now start going through the more subjective and complex issues.

murchandamus commented at 8:23 pm on December 17, 2024: contributor

Okay, I should have addressed all open review comments. Thank you for your review, @JeremyRubin, @larryruane, @sipa, @EthanHeilman, and @achow101.

in bip-update-process.md:8 in f52a0c0621 outdated

0@@ -0,0 +1,708 @@
1+```
2+BIP: ?
3+Title: Updated BIP Process
4+Author: Murch <murch@murch.one>
5+Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-Updated-BIP-Process
6+Status: Draft
7+Type: Process
8+Created: 2024-05-13

jonatack commented at 9:29 pm on December 17, 2024:

Note to replace this date with the day a number is assigned.

murchandamus commented at 3:53 pm on December 19, 2024:

Replaced with “?” for the time being.

in bip-update-process.md:26 in f52a0c0621 outdated

21+## Motivation
22+
23+BIP 2 is over eight years old and was written when different concerns were pressing to the Bitcoin[^capitalization]
24+community. The BIP process as defined by BIP 2 thus far seems to have been fashioned to facilitate the design and
25+activation of protocol changes. In the past years, BIPs more often describe interoperable features beyond the base
26+protocol. The community has had multiple debates about the role of BIP Editors, and some aspects of the process

jonatack commented at 9:32 pm on December 17, 2024:

prefer direct over passive voice and other grammar fixups

0protocol. The community has debated repeatedly about the role of the BIP Editors and aspects of the process

in bip-update-process.md:24 in f52a0c0621 outdated

19+address the evolving needs of the BIP process.
20+
21+## Motivation
22+
23+BIP 2 is over eight years old and was written when different concerns were pressing to the Bitcoin[^capitalization]
24+community. The BIP process as defined by BIP 2 thus far seems to have been fashioned to facilitate the design and

jonatack commented at 9:34 pm on December 17, 2024:

0community. The BIP process as defined by BIP 2 aimed to facilitate the design and

in bip-update-process.md:25 in f52a0c0621 outdated

20+
21+## Motivation
22+
23+BIP 2 is over eight years old and was written when different concerns were pressing to the Bitcoin[^capitalization]
24+community. The BIP process as defined by BIP 2 thus far seems to have been fashioned to facilitate the design and
25+activation of protocol changes. In the past years, BIPs more often describe interoperable features beyond the base

jonatack commented at 9:36 pm on December 17, 2024:

BIPs involving protocol changes are still being proposed, so I’m not sure about this sentence and if it is necessary.

0activation of protocol changes. In the past years, BIPs have more often described interoperational standards beyond the base

in bip-update-process.md:27 in f52a0c0621 outdated

22+
23+BIP 2 is over eight years old and was written when different concerns were pressing to the Bitcoin[^capitalization]
24+community. The BIP process as defined by BIP 2 thus far seems to have been fashioned to facilitate the design and
25+activation of protocol changes. In the past years, BIPs more often describe interoperable features beyond the base
26+protocol. The community has had multiple debates about the role of BIP Editors, and some aspects of the process
27+specified by BIP 2 that did not seem to achieve the intended goals. This proposal sunsets aspects of the BIP 2 process

jonatack commented at 9:37 pm on December 17, 2024:

0specified by BIP 2 that did not seem to achieve the intended goals. This BIP sunsets aspects of the BIP 2 process

in bip-update-process.md:39 in f52a0c0621 outdated

34+
35+BIPs cover the range of interests of the Bitcoin community. The main topic is technology that supports the Bitcoin
36+currency. Most BIPs provide a concise, self-contained, technical description of one new concept, feature, or standard.
37+Some BIPs describe processes, implementation guidelines, best practices, incident reports (e.g.
38+[BIP 50](bip-0050.mediawiki)), or other information relevant to the Bitcoin community. However, any topics related to
39+the Bitcoin protocol, Bitcoin’s peer-to-peer network, and Bitcoin client software may be acceptable.

jonatack commented at 9:39 pm on December 17, 2024:

0the Bitcoin protocol, peer-to-peer network, and client software may be acceptable.

in bip-update-process.md:53 in f52a0c0621 outdated

48+their proposal within the Bitcoin community.
49+
50+#### Authors and Shepherds
51+
52+Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign
53+one or more Shepherds to their BIP. Shepherds are stand in owners of a BIP who were not involved in writing the

jonatack commented at 9:40 pm on December 17, 2024:

0one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the

in bip-update-process.md:54 in f52a0c0621 outdated

49+
50+#### Authors and Shepherds
51+
52+Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign
53+one or more Shepherds to their BIP. Shepherds are stand in owners of a BIP who were not involved in writing the
54+document. They support the authors in advancing the proposal, or act as point-of-contact for the BIP in absence of the

jonatack commented at 9:41 pm on December 17, 2024:

0document. They support the authors in advancing the proposal, or act as a point of contact for the BIP in the absence of the

in bip-update-process.md:56 in f52a0c0621 outdated

51+
52+Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign
53+one or more Shepherds to their BIP. Shepherds are stand in owners of a BIP who were not involved in writing the
54+document. They support the authors in advancing the proposal, or act as point-of-contact for the BIP in absence of the
55+authors. Shepherds may perform the role of Authors for any aspect of the BIP process unless overruled by an Author.
56+Shepherds share ownership of the BIP at the discretion of the Authors.

jonatack commented at 9:42 pm on December 17, 2024:

Can an author revoke the shepherds? What if there are several authors?

Not sure if the addition of shepherds is useful, nor worth the additional process complexity.

The notion of herding sheep…heh :)

murchandamus commented at 4:18 pm on December 19, 2024:

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.

jonatack commented at 5:42 pm on January 4, 2025:

…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.

in bip-update-process.md:65 in f52a0c0621 outdated

60+BIPs do not define what Bitcoin is: individual BIPs do not represent Bitcoin community consensus or a general
61+recommendation for implementation. A BIP represents a personal recommendation by the BIP authors to the Bitcoin
62+community. Some BIPs may never be adopted. Some BIPs may be adopted by one or more Bitcoin clients or other related
63+software. Some may even end up changing the consensus rules that the Bitcoin ecosystem jointly enforces.
64+
65+### What is the purpose of the BIP repository?

jonatack commented at 9:47 pm on December 17, 2024:

Here and throughout this document.

0### What is the purpose of the BIPs repository?

murchandamus commented at 10:23 pm on December 18, 2024:

I had just changed that the other way per request of @real-or-random here: https://github.com/murchandamus/bips/pull/2#discussion_r1778753665. How about you two discuss here? ^^

murchandamus commented at 7:38 pm on December 26, 2024:

Thinking more about this, I would say “the Bitcoin Improvement Proposal repository”, not “the Bitcoin Improvement Proposals repository”, so seems right to me?

jonatack commented at 5:40 pm on January 4, 2025:

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.

murchandamus commented at 7:52 pm on January 15, 2025:

Okay, changed it back to “BIPs repository” throughout

murchandamus commented at 7:52 pm on January 15, 2025:

Changed it back to “BIPs repository” across the document

in bip-update-process.md:67 in f52a0c0621 outdated

62+community. Some BIPs may never be adopted. Some BIPs may be adopted by one or more Bitcoin clients or other related
63+software. Some may even end up changing the consensus rules that the Bitcoin ecosystem jointly enforces.
64+
65+### What is the purpose of the BIP repository?
66+
67+The [BIP repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals.

jonatack commented at 9:47 pm on December 17, 2024:

0The [BIPs repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals.

in bip-update-process.md:70 in f52a0c0621 outdated

65+### What is the purpose of the BIP repository?
66+
67+The [BIP repository](https://github.com/bitcoin/bips/) serves as a publication medium and archive for mature proposals.
68+Through its high visibility, it facilitates the community-wide consideration of BIPs and provides a well-established
69+source to retrieve the latest version of any BIP. The repository transparently records all changes to each BIP and
70+allows any community member to retain a complete copy of the archive easily.

jonatack commented at 9:49 pm on December 17, 2024:

0allows any community member to easily retain a complete copy of the archive.

murchandamus commented at 10:25 pm on December 18, 2024:

Y’all are killing me :grin:, @LarryRuane: #1712 (review)

murchandamus commented at 4:19 pm on December 19, 2024:

I don’t care one way or the other. Gonna leave it as is.

jonatack commented at 5:57 pm on January 27, 2025:

All good. I think Larry is correct.

in bip-update-process.md:80 in f52a0c0621 outdated

75+### What is the scope of the BIP repository?
76+
77+The BIP repository is focused on information and technologies that aim to support and expand the utility of the bitcoin
78+currency. Related topics that are of interest to the Bitcoin community may be acceptable. The scope of the BIP
79+repository is limited to BIPs that do not oppose the fundamental principle that Bitcoin constitutes a peer-to-peer
80+electronic cash system for the bitcoin currency.

jonatack commented at 9:53 pm on December 17, 2024:

Line 33-42 above also appear to discuss the scope. Suggest a single point of truth in this document that defines the scope of BIPs.

murchandamus commented at 4:34 pm on December 19, 2024:

Okay, folded this section into “What is a BIP?”

in bip-update-process.md:86 in f52a0c0621 outdated

81+
82+## BIP format and structure
83+
84+### Specification
85+
86+BIPs should be written in MediaWiki or Markdown[^markdown] format.

jonatack commented at 9:54 pm on December 17, 2024:

0Authors may choose to submit BIPs in MediaWiki or Markdown[^markdown] format.

jonatack commented at 9:54 pm on December 17, 2024: member

Began WIP re-review of the latest version. In some places the writing can be pithier (more concise/direct). See also the comments below pertaining to the repo name, the shepherds, and the BIPs scope.

in bip-update-process.md:211 in f52a0c0621 outdated

206+
207+The BIP process starts with a new idea for Bitcoin. Each potential BIP must have authors—people who write the BIP,
208+gather feedback, shepherd the discussion in the appropriate forums, and finally recommend a mature proposal to the
209+community.
210+
211+![Status Diagram](bip-update-process/status-diagram.png "Status Diagram for the BIP Workflow")

katesalazar commented at 4:59 pm on December 18, 2024:

this is readable when using dark mode, but a bit low contrast. What do you think?

EthanHeilman commented at 5:20 pm on December 18, 2024:

Is there a reason Closed is grey font, grey lines but all the other states are black font, black lines?

murchandamus commented at 4:55 pm on December 19, 2024:

No strong reasons. I changed it to black.

jonatack added the label New BIP on Dec 18, 2024

in bip-update-process.md:10 in f52a0c0621 outdated

 5+Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-Updated-BIP-Process
 6+Status: Draft
 7+Type: Process
 8+Created: 2024-05-13
 9+License: BSD-2-Clause
10+Post-History: https://github.com/murchandamus/bips/pull/2

murchandamus commented at 3:54 pm on December 19, 2024:

Added the mailing list discussion about “Time for an update to BIP 2?”

murchandamus commented at 4:56 pm on December 19, 2024: contributor

I addressed all open feedback. Thanks @jonatack, @katesalazar, and @EthanHeilman.

JeremyRubin commented at 5:46 pm on December 21, 2024: contributor

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.

murchandamus added the label Needs number assignment on Dec 27, 2024

in bip-update-process.md:43 in d6e4b5a2ae outdated

38+Some BIPs describe processes, implementation guidelines, best practices, incident reports (e.g.,
39+[BIP 50](bip-0050.mediawiki)), or other information relevant to the Bitcoin community. However, any topics related to
40+the Bitcoin protocol, peer-to-peer network, and client software may be acceptable.
41+
42+BIPs are intended to be the primary mechanism for proposing new protocol features, coordinating client standards, and
43+documenting design decisions that have gone into implementations. BIPs may be submitted by anyone.

kanzure commented at 9:59 pm on December 31, 2024:

“primary mechanism” might be overly strong here, and might point to levels of processes that don’t exist.

murchandamus commented at 7:22 pm on January 15, 2025:

Okay, I replaced it with “a means”:

0BIPs are intended to be a means for proposing new protocol features, coordinating client standards, and
1documenting design decisions that have gone into implementations. BIPs may be submitted by anyone.

in bip-update-process.md:78 in d6e4b5a2ae outdated

73+Through its high visibility, it facilitates the community-wide consideration of BIPs and provides a well-established
74+source to retrieve the latest version of any BIP. The repository transparently records all changes to each BIP and
75+allows any community member to retain a complete copy of the archive easily.
76+
77+The BIP repository is not a tool to track acceptance[^acceptance], adoption, or community consensus on BIPs, beyond
78+providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.

kanzure commented at 10:02 pm on December 31, 2024:

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.

murchandamus commented at 8:27 pm on January 15, 2025:

It seems to me that the prior section “What is the significance of BIPs?” gets into this a bit. However, I added

0The BIP repository is not a tool to track acceptance[^acceptance], adoption, or community consensus on BIPs, beyond
1providing a brief overview of BIP statuses (see [Workflow](#workflow) below) to the audience.
2There is no formal or informal decision body that governs Bitcoin development or decides acceptance of BIPs. Bitcoin
3development 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.

in bip-update-process.md:387 in d6e4b5a2ae outdated

382+### Specification
383+
384+Each new BIP must identify at least one acceptable license in its preamble. Licenses must be referenced per their
385+respective [SPDX License identifier](https://spdx.org/licenses). New BIPs may be accepted with the licenses described
386+below.
387+

kanzure commented at 10:06 pm on December 31, 2024:

One or two sentences about the motivation behind our interest in freely licensed BIPs could be helpful to include.

murchandamus commented at 9:22 pm on January 15, 2025:

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.

in bip-update-process.md:489 in d6e4b5a2ae outdated

484+* Motivation, Rationale, and Backward Compatibility have been addressed
485+* Specification provides sufficient detail for implementation
486+* The defined Layer header must be correctly assigned for the given specification
487+* The BIP is ready: it is comprehensible, technically feasible, and all aspects are addressed as necessary
488+
489+Editors do NOT evaluate whether the proposal is likely to be adopted.

kanzure commented at 10:08 pm on December 31, 2024:

“The idea must be of interest to the broader community or relevant to multiple software projects.”

murchandamus commented at 9:23 pm on January 15, 2025:

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?

in bip-update-process.md:115 in d6e4b5a2ae outdated

110+appear in the following order. Headers marked with "\*" are optional. All other headers are required. The overview is
111+followed by an explanation for each header.
112+
113+```
114+  BIP: <BIP number, or "?" before assignment>
115+* Layer: <Consensus (soft fork) | Consensus (hard fork) | Peer Services | API/RPC | Applications>

kanzure commented at 10:10 pm on December 31, 2024:

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).

murchandamus commented at 8:31 pm on January 15, 2025:

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.

in bip-update-process.md:28 in d6e4b5a2ae outdated

23+
24+BIP 2 is over eight years old and was written when different concerns were pressing to the Bitcoin[^capitalization]
25+community. The BIP process as defined by BIP 2 aimed to facilitate the design and
26+activation of protocol changes. In the past years, BIPs have more often described interoperational standards beyond the base
27+protocol. The community has debated repeatedly about the role of the BIP Editors, and aspects of the process
28+specified by BIP 2 that did not seem to achieve the intended goals. This BIP sunsets aspects of the BIP 2 process

jonatack commented at 5:35 pm on January 4, 2025:

Suggest keeping only the last sentence of this paragraph.

Also, as mentioned in #1712 (review), we are seeing quite a few new BIPs for protocol changes nowadays.

murchandamus commented at 6:48 pm on January 15, 2025:

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.

murchandamus commented at 9:12 pm on February 10, 2025:

I revisited this comment and trimmed the Motivation further.

jonatack commented at 5:44 pm on January 4, 2025: member

Am re-reviewing this BIP today. A few initial comments.

in bip-update-process.md:120 in d6e4b5a2ae outdated

115+* Layer: <Consensus (soft fork) | Consensus (hard fork) | Peer Services | API/RPC | Applications>
116+  Title: <BIP title (≤ 50 characters)>
117+  Authors: <Authors’ names and email addresses>
118+* Shepherds: <Shepherds’ names and email addresses>
119+  Status: <Draft | Complete | Deployed | Closed>
120+  Type: <Specification | Informational | Process>

jonatack commented at 11:08 pm on January 7, 2025:

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?

murchandamus commented at 8:36 pm on January 15, 2025:

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.

jonatack commented at 6:07 pm on January 27, 2025:

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.

in bip-update-process.md:121 in d6e4b5a2ae outdated

116+  Title: <BIP title (≤ 50 characters)>
117+  Authors: <Authors’ names and email addresses>
118+* Shepherds: <Shepherds’ names and email addresses>
119+  Status: <Draft | Complete | Deployed | Closed>
120+  Type: <Specification | Informational | Process>
121+  Created: <Date of number assignment, or "?" before assignment>

jonatack commented at 11:11 pm on January 7, 2025:

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.

murchandamus commented at 8:37 pm on January 15, 2025:

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.

in bip-update-process.md:125 in d6e4b5a2ae outdated

120+  Type: <Specification | Informational | Process>
121+  Created: <Date of number assignment, or "?" before assignment>
122+  License: <Identifier(s) of acceptable license(s)>
123+* License-Code: <Identifier(s) for Code under different acceptable license(s)>
124+* Discussion: <Mailing list thread(s), or other noteworthy discussion(s) in "date: URL" format>
125+* Revision: <Version number (MAJOR.MINOR.PATCH)>

jonatack commented at 11:18 pm on January 7, 2025:

As the Changelog lists dates/versions/descriptions and follows semver, would call this field “Version” and mention here that it follows semver.

murchandamus commented at 9:12 pm on February 10, 2025:

I adopted this suggestion.

in bip-update-process.md:196 in d6e4b5a2ae outdated

191+### BIP types
192+
193+* A **Specification BIP** defines a set of technical rules affecting the interoperability of implementations. The
194+  distinguishing feature of a Specification BIP is that it can be implemented, and implementations can be compliant with
195+  it. Specification BIPs should come with or refer to a reference implementation and preferably provide test vectors.
196+* An **Informational BIP** describes a Bitcoin design issue, provides general guidelines or other information to the

jonatack commented at 11:30 pm on January 7, 2025:

0* An **Informational BIP** describes a Bitcoin design issue, or provides general guidelines or other information to the

in bip-update-process.md:215 in d6e4b5a2ae outdated

210+
211+### Ideation
212+
213+After having an idea, the authors should evaluate whether it meets the criteria to become a BIP, as described in this
214+BIP. The idea must be of interest to the broader community or relevant to multiple software projects. Minor improvements
215+and matters concerning only a single project usually do not require standardization and should instead be brought up directly to

jonatack commented at 11:34 pm on January 7, 2025:

If I’m not confused, this shouldn’t pertain to Process BIPs.

murchandamus commented at 8:39 pm on January 15, 2025:

I don’t follow. What doesn’t pertain to Process BIPs?

in bip-update-process.md:262 in d6e4b5a2ae outdated

257+
258+Proposals are also not ready for number assignment if they duplicate efforts, disregard formatting rules, are too
259+unfocused or too broad, fail to provide proper motivation, fail to address backward compatibility where necessary, or
260+fail to specify the feature clearly and comprehensively. Reviewers and BIP editors should provide guidance on how the
261+proposal may be improved to progress toward readiness. Pull requests that are proposing off-topic or unserious ideas or
262+have stopped making progress may be closed.

jonatack commented at 11:37 pm on January 7, 2025:

0that have stopped making progress may be closed.

in bip-update-process.md:258 in d6e4b5a2ae outdated

253+improving the proposal based on community feedback, will be assigned a number by a BIP editor. The BIP editors should
254+delay number assignment when they perceive a proposal being met with lack of interest: number assignment facilitates the
255+distributed discussion of ideas, but before a proposal garners some interest in the Bitcoin community, there is no need
256+to refer to it by a number.
257+
258+Proposals are also not ready for number assignment if they duplicate efforts, disregard formatting rules, are too

jonatack commented at 11:42 pm on January 7, 2025:

A mention of or reference to the scope of BIPs described lines 45-47 would be helpful in this sentence.

murchandamus commented at 9:32 pm on January 15, 2025:

If something is out of scope, it’s offtopic, so it seems unnecessary to additionally mention that it’s not eligible for number assignment.

in bip-update-process.md:315 in d6e4b5a2ae outdated

310+
311+##### Draft ↦ Closed
312+
313+BIP authors may decide on their own to change their BIP’s status from Draft to Closed. If a Draft BIP stops making
314+progress, sees accumulated feedback unaddressed, or otherwise appears stalled for a year, the community may move the BIP
315+to Closed unless the authors assert that they intend to continue work when contacted.

jonatack commented at 11:46 pm on January 7, 2025:

It may be a good idea to provide a time frame here for considering when authors are non-responsive or no longer reachable.

kanzure commented at 2:37 pm on January 8, 2025:

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.

murchandamus commented at 8:59 pm on January 15, 2025:

Sure, I also put a four week limit for reactions here

in bip-update-process.md:370 in d6e4b5a2ae outdated

365+### Transferring BIP Ownership
366+
367+It occasionally becomes necessary to transfer ownership of BIPs to new owners. In general, it would be preferable to
368+retain the original authors of the transferred BIP, but that is up to the original authors. A good reason to transfer
369+ownership is because the original authors no longer have the time or interest in updating it or following through with
370+the BIP process, or have fallen off the face of the 'net (i.e., are unreachable or not responding to email). A bad reason

jonatack commented at 11:52 pm on January 7, 2025:

0the BIP process, or are unreachable or unresponsive. A bad reason

in bip-update-process.md:378 in d6e4b5a2ae outdated

373+competing BIP.
374+
375+If someone is interested in assuming ownership of a BIP, they should send an email asking to take over, addressed to the
376+original authors, the BIP Editors, and the Bitcoin Development Mailing List. If the authors do not respond in a timely
377+manner (e.g., two weeks), the BIP editors will make a unilateral decision whether to appoint the applicants as
378+[Shepherds](#authors-and-shepherds) (which may be amended should the original authors make a delayed reappearance).

jonatack commented at 11:54 pm on January 7, 2025:

If the BIP is in draft, a new owner may be an author as well? (It would be simpler to have a single role)

jonatack commented at 11:56 pm on January 7, 2025: member

Continuing WIP iterative review…

Edit: this draft is quite long. It would be good if we can make it pithier.

jonatack removed the label Needs number assignment on Jan 9, 2025

jonatack commented at 12:45 pm on January 9, 2025: member

Assigned BIP 3.

jonatack renamed this:
~~An updated BIP Process~~
BIP3: An updated BIP Process
on Jan 9, 2025

murchandamus commented at 9:38 pm on January 15, 2025: contributor

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.

murchandamus commented at 10:33 pm on January 15, 2025: contributor

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.

murchandamus force-pushed on Jan 16, 2025

murchandamus commented at 3:29 pm on January 16, 2025: contributor

Fixed an issue to get the checks to pass. I think I’m caught up on all the review comments.

in bip-0003.md:121 in 2a0c232a67 outdated

116+  BIP: <BIP number, or "?" before assignment>
117+* Layer: <Consensus (soft fork) | Consensus (hard fork) | Peer Services | API/RPC | Applications>
118+  Title: <BIP title (≤ 50 characters)>
119+  Authors: <Authors’ names and email addresses>
120+* Shepherds: <Shepherds’ names and email addresses>
121+  Status: <Draft | Complete | Deployed | Closed; see [Workflow](#workflow)>

murchandamus commented at 5:55 pm on January 27, 2025:

The links in the preformatted preamble don’t work. Move it back into sections below.

in bip-0003.md:113 in 2a0c232a67 outdated

109+#### BIP header preamble
110+
111+Each BIP must begin with an [RFC 822-style header preamble](https://www.w3.org/Protocols/rfc822/). The headers must
112+appear in the following order. Headers marked with "\*" are optional. All other headers are required. The overview is
113+followed by an explanation for each header.
114+

murchandamus commented at 5:56 pm on January 27, 2025:

Changed recently that only some are explained, not all.

murchandamus commented at 6:13 pm on January 27, 2025: contributor

Was just looking over the BIP and found the following two issues to be addressed shortly:

in bip-0003.md:515 in 2a0c232a67 outdated

510+- The Status field is no longer modeled around the workflow of consensus changes.
511+- Status field values are reduced from nine to four:
512+  - Deferred, Obsolete, Rejected, Replaced, and Withdrawn are gathered up into Closed.[^closed]
513+  - Final and Active are collapsed into Deployed.
514+  - The remaining statuses are Draft, Complete, Deployed, and Closed.
515+- BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection]

jonatack commented at 6:17 pm on January 27, 2025:

Maybe

0- 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)

murchandamus commented at 3:57 pm on January 29, 2025:

Taken and updated in OP

maaku commented at 4:41 am on February 4, 2025:

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.

in bip-0003.md:360 in 2a0c232a67 outdated

355+to transfer ownership is because someone doesn't agree with the direction of the BIP. The community tries to build
356+consensus around a BIP, but if that's not possible, rather than fighting over control, the dissenters should supply a
357+competing BIP.
358+
359+If someone is interested in assuming ownership of a BIP, they should send an email asking to take over, addressed to the
360+original authors, the BIP Editors, and the Bitcoin Development Mailing List. If the authors do not respond in a timely

jonatack commented at 6:20 pm on January 27, 2025:

0original authors, the BIP Editors, and the Bitcoin Development Mailing List. If the authors are unreachable or do not respond in a timely

murchandamus commented at 3:52 pm on January 29, 2025:

Taken, but isn’t being unreachable a subset of “not responding in a timely manner”?

jonatack commented at 6:26 pm on January 29, 2025:

I see (thanks!) By “unreachable”, I wanted to mean that we don’t know how to reach them.

murchandamus commented at 7:24 pm on January 29, 2025:

We should have an email address for every BIP Author, but either way it’s a fine addition

in bip-0003.md:516 in 2a0c232a67 outdated

511+- Status field values are reduced from nine to four:
512+  - Deferred, Obsolete, Rejected, Replaced, and Withdrawn are gathered up into Closed.[^closed]
513+  - Final and Active are collapsed into Deployed.
514+  - The remaining statuses are Draft, Complete, Deployed, and Closed.
515+- BIPs no longer get rejected solely on grounds of not making progress for three years.[^rejection]
516+- 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

jonatack commented at 6:20 pm on January 27, 2025:

Can a Complete or Deployed PR be closed, and under what conditions.

0- 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)

murchandamus commented at 3:59 pm on January 29, 2025:

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

in bip-0003.md:57 in 2a0c232a67 outdated

52+expected to foster discussion, address feedback and dissenting opinions, and, if applicable, advance the adoption of
53+their proposal within the Bitcoin community.
54+
55+#### Authors and Shepherds
56+
57+Authors may want additional support with the BIP process after writing an initial draft. In that case, they may assign

jonatack commented at 6:43 pm on January 27, 2025:

“support with” -> “help with” or “support for”

in bip-0003.md:94 in 2a0c232a67 outdated

89+following list and address each as appropriate. For some BIPs, some concerns may not warrant a dedicated section.
90+
91+* Preamble -- Headers containing metadata about the BIP (see the section [BIP header preamble](#bip-header-preamble)
92+  below).
93+* Abstract -- A short description of the technical issue being addressed.
94+* Motivation -- The motivation is critical for BIPs. It should clearly explain what issue the BIP addresses, and how the

jonatack commented at 6:48 pm on January 27, 2025:

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”)

murchandamus commented at 4:30 pm on January 29, 2025:

Thanks good catch. Rewrote the Motivation description.

in bip-0003.md:98 in 2a0c232a67 outdated

93+* Abstract -- A short description of the technical issue being addressed.
94+* Motivation -- The motivation is critical for BIPs. It should clearly explain what issue the BIP addresses, and how the
95+  existing situation is inadequate to address the problem that the BIP solves.
96+* Specification -- The technical specification should describe the syntax and semantics of any new feature. The
97+  specification should be detailed enough to enable any Bitcoin project to create an interoperable implementation.
98+* Rationale -- The rationale fleshes out the specification by describing what motivated the design and why particular

jonatack commented at 6:52 pm on January 27, 2025:

maybe avoid the word “motivated” here as it is also a section title

murchandamus commented at 4:33 pm on January 29, 2025:

Slightly amended this sentence.

in bip-0003.md:327 in 2a0c232a67 outdated

322+Closed BIP to Draft status.
323+
324+### Changelog
325+
326+To help implementers understand updates to a BIP, any changes after it has reached Complete must be tracked with version,
327+date, and description in a Changelog section. The version number is inspired by semantic versioning (MAJOR.MINOR.PATCH).

jonatack commented at 6:58 pm on January 27, 2025:

Suggest stipulating that entries be ordered by most recent first / descending date (i.e. like in https://keepachangelog.com/)

murchandamus commented at 3:44 pm on January 29, 2025:

Good idea. I adopted this suggestion, revisited the Changelog section, and added an example for a Changelog as well.

in bip-0003.md:444 in 2a0c232a67 outdated

439+* Luke Dashjr ([luke_bipeditor@dashjr.org](mailto:luke_bipeditor@dashjr.org))
440+* Mark "Murch" Erhardt ([murch@murch.one](mailto:murch@murch.one))
441+* Olaoluwa Osuntokun ([laolu32@gmail.com](mailto:laolu32@gmail.com))
442+* Ruben Somsen ([rsomsen@gmail.com](mailto:rsomsen@gmail.com))
443+
444+### BIP Editor Responsibilities & Workflow

jonatack commented at 7:00 pm on January 27, 2025:

nit, can be done later, consistent capitalization of the different section titles

murchandamus commented at 4:21 pm on January 29, 2025:

Took care of that!

murchandamus force-pushed on Jan 29, 2025

murchandamus commented at 4:22 pm on January 29, 2025: contributor

Caught up on @jonatack’s review comments. Thank you for the review. I also revisited the Description of the Preamble and the Changelog.

murchandamus force-pushed on Jan 29, 2025

murchandamus renamed this:
~~BIP3: An updated BIP Process~~
BIP3: Updated BIP Process
on Jan 29, 2025

murchandamus force-pushed on Jan 29, 2025

murchandamus commented at 7:29 pm on January 29, 2025: contributor

Here’s the diff with the changes prompted by this last round of review in the past two weeks:

https://github.com/bitcoin/bips/compare/4241144a4453a3b20fc5cfe5a62edf2f0fd35c72..bc9f98bafd4d16eb233960fe0c572b9f950a50cb

in bip-0003.md:60 in 8412eccd13 outdated

57+Authors may want additional help with the BIP process after writing an initial draft. In that case, they may assign
58+one or more Shepherds to their BIP. Shepherds are stand-in owners of a BIP who were not involved in writing the
59+document. They support the authors in advancing the proposal, or act as a point of contact for the BIP in the absence of the
60+authors. Shepherds may perform the role of Authors for any aspect of the BIP process unless overruled by an Author.
61+Shepherds share ownership of the BIP at the discretion of the Authors.
62+

kallewoof commented at 3:57 am on February 4, 2025:

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.)

murchandamus commented at 8:27 pm on February 4, 2025:

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.

bitcoin3us commented at 5:46 pm on February 15, 2025:

Apologies if I’m late to this review opportunity. This is my first bip ‘review’ I’m responding to the Bitcoin Optech Newsletter #341 email.

If “Shepherd” is meant to signify “Secondary Owner”, for simplicity why not use that exact term? This would remove any need for readers to look up the meaning of Shepherd in this context.

If Secondary Owner isn’t an option, have alternatives like “Delegate” or “Trustee” been considered? These terms have clear, widely understood definitions and, if applicable, could enhance clarity.

Thank you for considering my suggestions.

murchandamus commented at 9:03 pm on February 15, 2025:

Thank you @bitcoin3us for sharing your thoughts. I have revised my proposal to use “Deputy” instead of “Shepherd”. Please let me know if that sounds right to you.

in bip-0003.md:292 in 8412eccd13 outdated

287+
288+#### Closed[^closed]
289+
290+A BIP that is _not in active use_, may be labeled Closed when its authors have stopped working on it, no longer
291+recommend the proposed approach, or no longer pursue adoption of their Complete proposal. The reason for moving the
292+proposal to Closed should be recorded in the Changelog section in the same commit that updates the status.

kallewoof commented at 4:02 am on February 4, 2025:

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.

maaku commented at 4:36 am on February 4, 2025:

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?

murchandamus commented at 8:07 pm on February 4, 2025:

@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.

murchandamus commented at 8:15 pm on February 4, 2025:

@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?

ajtowns commented at 8:46 am on February 7, 2025:

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.

murchandamus commented at 4:53 pm on February 7, 2025:

Thanks, what you propose makes the section clearer. I took all of this with a small adjustment in the last sentence:

0-However if it is obvious that the new attempt directly continues work on the same idea, 
1-in which case it may be reasonable to return the Closed BIP to Draft status.
2+However, if it is obvious that the new attempt directly continues work on the same idea,
3+it may be reasonable to return the Closed BIP to Draft status.

maaku commented at 11:38 am on February 8, 2025:

@murchandamus The section you reference lists examples, not a definition. This may seem overly legalistic in interpretation, but these are standards (or the closest thing bitcoin has to standards). Semantics matter.

“deployed to mainnet, activated softfork, or rough consensus demonstrated” are given as examples. No indication is given that these are exhaustive, or what other constraints might be in place. No definition at all is offered up. A random passer-by could mark a BIP as Closed due to inactivity because vibes, or because it’s Tuesday, or because they feel like it, and that would be in strict compliance with the rules given here.

It would help if “active use” were eliminated entirely. There are BIPs for which determination of “active use” is nontrivial and perhaps even subjective. BIP 98, for example, hasn’t been updated in years, and is not used in any bitcoin consensus code. But there are multiple non-consensus-code implementations outside of the upstream bitcoin core repository and in bitcoin-adjacent projects, including a patch set that adds a built-in stratum server, and consensus features inside of Blockstream’s Liquid product. The BIP isn’t final because it could still see changes before it sees more permanent adoption, e.g. in upstreaming the stratum server. Nor should it be retired due to the mere passage of time–I’ve had to object to multiple attempts to do so over the years.

Maybe you think it’s adequate that a BIP be closed if someone can’t be reached in 4 weeks. For me, I am balancing multiple projects of much higher priority on a day-to-day basis, and it is entirely possible a single email could get lost in that, especially given the noise of GitHub notifications (and the fact that I was previously not tagged on pull requests to close these BIPs). It is stressful and aggravating.

jonatack commented at 10:47 pm on February 12, 2025:

Fair enough, “active use” is employed at least 6 times in this BIP and could use a definition at the top.

Maybe the multiple “four weeks” periods in this BIP could be six or eight weeks instead, not sure what others think. It may also be worthwhile to standardize on a single warning time period, for simplicity.

maaku commented at 3:23 am on February 15, 2025:

What about cases, like real example I gave, where indefinite status in the Draft stage is exactly what’s desired and moving to Closed is an anti feature?

murchandamus commented at 8:39 pm on February 15, 2025:

I think what is being missed here, is that the situation would be extremely simple, if we were to take a legalistic approach. BIP2 states that a BIP that hasn’t made progress for three years should be rejected:

The Bitcoin Process is not a legal framework. It’s a set of guidelines that help align the authors’ and editors’ expectations, and aim to provide information to the Bitcoin developer community. The status field especially highlights to the audience which BIPs they may want to review, implement, or otherwise pay attention to. The point of the discussed rules is to save the audience time looking into BIPs that nobody is working on.

I have been pondering how to define active use, but it might be more of a “I know it when I see it” sort of thing. The opposite, “not being in active use” may be easier to define, but either way, it boils down to some stakeholder making a cogent claim that something is being used.

BIPs do not only track consensus changes. If a BIP is in active use by any Bitcoin project, it should be updated to Deployed.

If a BIP has not been relevant to the Bitcoin ecosystem for years and there is no active effort going into changing that, it should be Closed. That does not mean that the BIP is going to be deleted, nor does it preclude anyone from continuing to refer to the document. It just means that in the Bitcoin developer community nobody is actively working on advancing this BIP, and it is currently not deployed or otherwise actively used by any Bitcoin projects.

If a BIP is in active use by a Bitcoin-adjacent project or in Bitcoin-adjacent ecosystems, preferably a corresponding community should host the document in their own documentation. If a BIP is broadly used and for historical reasons the authoritative source is the BIPs repository, I don’t see a problem with it being set to Complete in the BIPs Repository with a note at the top or in the Changelog describing the situation and suggesting that it should not be Closed for historical reasons. It’s not like we have not grandfathered in things before. I’d even be open to setting it to Deployed with such a note.

Maybe you are also missing why I’m introducing this new rule in the first place. We have several open pull requests that propose closing BIPs under the “three years of no progress” rule. My idea was that the new rule that states “one year of no progress and authors do not respond when contacted” would give us standing to close pull request #1008 and keep BIP 117 open, because that seems to be what we have been doing for the past few years anyway. OTOH, it still allows us to move BIPs that actually nobody uses, nobody is working on, and nobody is pushing for to Closed. E.g., allowing us to move forward with merging #1009 and #792.

I would like to find an end to this debate. In order of preference, this could be achieved by adopting a superior guideline how to handle the situation (e.g., by someone proposing a better definition for active use, and/or providing a superior approach to the trade-off between being able to tidy out abandoned proposals from yore but also respecting if authors continue to be invested), sticking to my current proposal of “keep open BIPs whose authors continue to be invested”, or simply applying BIP2 as written. The option that I’m not interested in, is spending another 5–10 hours on a pointless debate when I’m trying to do you a favor. Please let me know what you would prefer, because like you, I have more useful things to spend my time on.

maaku commented at 9:15 pm on February 15, 2025:

Yes, I’m aware of why BIP 3 exists. I believe I’m the one who instigated this process, when it was identified that BIP 2 had the unintended ability to expire active BIPs. Some of those pull requests you mention were against my BIPs. I’m literally the first author to respond to #1008 where I requested the issue (not the BIP, but #1008) to be closed. You can close that issue. I don’t know why it is still open.

If you are asking my opinion, I think we shouldn’t have a Closed state. There should perhaps be a “Retracted” that only the author should be allowed to move a BIP into, and which could be objected to by any community member—this would be for proposals that were never more than a proposal and the authors explicitly want to remove from consideration. Even that I don’t think is strictly necessary.

I do not see the value of a BIP repository being a list of active and relevant BIPs. That is typically not the purpose of a standards repository, and introduces a whole new political angle of people wanting to influence what is or isn’t on the “active” list. It is a place to hash out agreement over ideas and implementations, but not their adoption or perceived continuing relevance.

murchandamus commented at 8:53 pm on February 18, 2025:

Yes, I’m aware of why BIP 3 exists. I believe I’m the one who instigated this process, when it was identified that BIP 2 had the unintended ability to expire active BIPs.

Mark, not every Bitcoin-related initiative is about you. I believe this concern has been sufficiently addressed. I will not spend more time on this.

sipa commented at 9:55 pm on February 18, 2025:

I don’t think the discourse here is very constructive, so let me try to mediate a bit.

Yes, I’m aware of why BIP 3 exists. I believe I’m the one who instigated this process, when it was identified that BIP 2 had the unintended ability to expire active BIPs. Some of those pull requests you mention were against my BIPs.

While I didn’t contribute much to BIP3, I have watched the proposal take shape and the discussions that led to it. As far as I remember, no, that was not at all what sparked what has now become BIP 3. The primary criticism with the current process that it wanted to address, I believe, was the fact that it involved too many judgement calls by Editors about community acceptance (more about that later).

You can close that issue. I don’t know why it is still open.

By the currently-active BIP 2 rules, #1008 should be merged, as BIP 117 should be marked as Expired. You’re free to disagree with the process of course, but as per the current process, it is really not up to you to reject it being marked Expired.

If you are asking my opinion, I think we shouldn’t have a Closed state. There should perhaps be a “Retracted” that only the author should be allowed to move a BIP into, and which could be objected to by any community member—this would be for proposals that were never more than a proposal and the authors explicitly want to remove from consideration. Even that I don’t think is strictly necessary.

The different states was one of the things that were heavily debated before the creation of BIP 3; specifically to what extent BIPs should have a notion of being “Active”, and who could make that call, and whether all the different types of “closed” that existed in BIP 1 and BIP 2 were really necessary. The result, in the current BIP 3 draft, is a significant simplification of those states, and far fewer judgment calls by Editors. It still has some reflection of adoption, as many commenters felt that was useful (I believe I argued for no “Active” state personally for example, but that appeared too controversial).

So I think you’re not appreciating the fact that BIP 3 is (if I had to guess) much closer to what you’d like the process to be than BIP 2 is. It seems you disagree with the result still for not going far enough, and not leaving the option open for leaving BIPs indefinitely open in certain circumstances, but the fact that “Author is responsive” is sufficient reason to leave something open is new in BIP 3, and I imagine something you’d prefer over the current alternative.

I do not see the value of a BIP repository being a list of active and relevant BIPs. That is typically not the purpose of a standards repository, and introduces a whole new political angle of people wanting to influence what is or isn’t on the “active” list. It is a place to hash out agreement over ideas and implementations, but not their adoption or perceived continuing relevance.

I largely agree, but the process was inherited from the Python PEP process (see PEP 1) which very much does include a determination of Active or not, and has changed substantially since. I think BIP 3 is a further departure from those origins, and I think one in the right direction.

kallewoof commented at 2:06 am on February 19, 2025:

By the currently-active BIP 2 rules, #1008 should be merged, as BIP 117 should be marked as Expired. You’re free to disagree with the process of course, but as per the current process, it is really not up to you to reject it being marked Expired.

Yes, but that’s not at all why that rule was put in place in the first place. Rejection should not be a mere timer. These are after all proposals and I don’t really see a reason to gate keep them in this manner, which is why I am not entirely happy with the “closed” idea either. If the argument is that a swarm of hypothetical engineers suddenly appear out of nowhere and decide to implement every bitcoin feature from scratch without consulting anyone (thus needing to know whether something is “active” or not), I would say that the swarm should learn to communicate.

murchandamus commented at 6:43 pm on February 20, 2025:

I updated the guidance regarding the Closed state to indicate that Complete BIPs can only be moved to Closed by their authors, and may stay open indefinitely. “Complete” indicates that the planned work on the BIP is concluded, and that the authors are recommending it for adoption, however, such BIPs may still be amended as issues are discovered when they are being deployed. I hope that these changes in combination with advancing the above discussed BIPs to Proposed (before BIP 3 activates) or Complete after BIP 3 activates) resolves your concern.

murchandamus commented at 8:34 pm on February 4, 2025: contributor

Hey @kallewoof and @maaku, thanks for taking a look. I have responded to your comments, please let me know what you think.

in bip-0003.md:4 in 8412eccd13 outdated

0@@ -0,0 +1,709 @@
1+<pre>
2+  BIP: 3
3+  Title: Updated BIP Process
4+  Author: Murch <murch@murch.one>

ajtowns commented at 8:02 am on February 7, 2025:

<murch@murch.one> 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.

murchandamus commented at 4:07 pm on February 7, 2025:

Thank for pointing this out. Our formatting checker currently requires the tags <pre> and </pre> to encapsulate the preamble. That means that we would either need to have different formats for markdown and mediawiki, or change our formatting requirements and adjust all existing BIPs.

For the moment, I have opened #1759 to fix the unrendered email addresses in the existing markdown BIPs and fixed it here by using the HTML Entity Names as you proposed.

murchandamus commented at 4:26 pm on February 7, 2025:

Unfortunately, using the HTML Entity Names causes the formatting checker to fail, so this will need a more invasive fix. :-/ Still working on the approach.

murchandamus commented at 7:18 pm on February 10, 2025:

This is hopefully to be resolved by #1759, after which I’ll update here.

murchandamus commented at 8:34 pm on February 10, 2025:

Great, that worked!

in bip-0003.md:11 in 8412eccd13 outdated

 6+  Status: Draft
 7+  Type: Process
 8+  Created: 2025-01-09
 9+  License: BSD-2-Clause
10+  Post-History: https://github.com/murchandamus/bips/pull/2
11+                https://gnusha.org/pi/bitcoindev/59fa94cea6f70e02b1ce0da07ae230670730171c.camel@timruffing.de/#t

ajtowns commented at 8:12 am on February 7, 2025:

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:

0## Discussion
1
2 * 2024-05-14 https://github.com/murchandamus/bips/pull/2
3 * 2024-04-02 https://gnusha.org/pi/bitcoindev/59fa94cea6f70e02b1ce0da07ae230670730171c.camel@timruffing.de/#t

murchandamus commented at 4:09 pm on February 7, 2025:

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?

murchandamus commented at 4:33 pm on February 7, 2025:

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.

ajtowns commented at 10:30 am on February 8, 2025:

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.

murchandamus commented at 7:17 pm on February 10, 2025:

Thanks for elaborating, I see where you are coming from.

murchandamus commented at 7:30 pm on February 19, 2025:

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 commented at 6:11 pm on February 21, 2025:

@ajtowns: Do you think it would be worth mentioning an optional “References” section that authors can use to link to related reading material?

ajtowns commented at 8:12 pm on February 21, 2025:

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?

ajtowns commented at 8:54 am on February 7, 2025: contributor

LGTM, ship it?

murchandamus commented at 4:54 pm on February 7, 2025: contributor

Thanks @ajtowns, I took your suggestions for improving the Closed section and continue to look into the non-rendering email addresses.

murchandamus force-pushed on Feb 10, 2025

in bip-0003.md:150 in f4955a586b outdated

145+               Anata Sample <anata@domain.example>
146+
147+* Shepherds — Additional owners of the BIP that are not authors. The Shepherds header uses the same format as the
148+  Authors header. See the [BIP Ownership](#bip-ownership) section above.
149+* Status — The stage of the workflow of the proposal. See the [Workflow](#workflow) section below.
150+* Type — See the [Bip types](#bip-types) section below for a description of the three BIP types.

jonatack commented at 10:18 pm on February 12, 2025:

0* Type — See the [BIP Types](#bip-types) section below for a description of the three BIP types.

(in general, check titles, their links, and that 68c21030804e3a5bfb8455f327dfa2d47f17dfd9 doesn’t introduce inconsistencies)

murchandamus commented at 8:19 pm on February 14, 2025:

Found another one, thanks

in bip-0003.md:350 in f4955a586b outdated

345+> * __1.0.0__ (2025-01-14):
346+>     * Complete planned work on the BIP.
347+
348+After a BIP receives a Changelog, the
349+Preamble must indicate the latest version in the Version header. The Changelog highlights revisions to BIPs to human readers. A single
350+BIP shall not recommend more than one variant of an idea at the same time. An an updated or

jonatack commented at 10:20 pm on February 12, 2025:

double “an”

0BIP shall not recommend more than one variant of an idea at the same time. An updated or

Maybe also s/An updated or competing variant/A different or competing/ for these reasons:

BIPs may have bugfixes or changes (cf top example in Changelog section), and;
Process BIPs are living documents that do not ossify and may be modified indefinitely.

murchandamus commented at 8:22 pm on February 14, 2025:

Taken, “a different or competing variant” better captures what I wanted to express.

in bip-0003.md:177 in f4955a586b outdated

172+
173+### BIP Types
174+
175+* A **Specification BIP** defines a set of technical rules affecting the interoperability of implementations. The
176+  distinguishing feature of a Specification BIP is that it can be implemented, and implementations can be compliant with
177+  it. Specification BIPs must have a Specification section, should have a Backward Compatibility section, and should come with or refer to a reference implementation and test vectors.

jonatack commented at 10:29 pm on February 12, 2025:

Per line 102, for clarity (also, aren’t backward compat sections required, or only encouraged?)

0  it. Specification BIPs must have a Specification section and a Backward Compatibility section, and for "Complete" status must include or refer to a reference implementation and test vectors.

murchandamus commented at 8:26 pm on February 14, 2025:

BIP 2 required Backward Compatibility sections, but this requirement had been dropped in BIP 3. I have added language to encourage Backward Compatibility sections in Specification BIPs as a compromise to accommodate a request to return them to mandatory from a recent reviewer. I am not convinced that every Specification BIP needs a Backward Compatibility section, and it seems fairly obvious when they are necessary or unnecessary.

jonatack commented at 10:37 pm on February 12, 2025: member

Partial re-review from looking at the recent change commits (will do a fresh review of the current document).

in bip-0003.md:375 in f4955a586b outdated

370+consensus around a BIP, but if that's not possible, rather than fighting over control, the dissenters should supply a
371+competing BIP.
372+
373+If someone is interested in assuming ownership of a BIP, they should send an email asking to take over, addressed to the
374+original authors, the BIP Editors, and the Bitcoin Development Mailing List. If the authors are unreachable or do not respond in a timely
375+manner (e.g., two weeks), the BIP editors will make a unilateral decision whether to appoint the applicants as

jonatack commented at 10:46 pm on February 12, 2025:

Two weeks seems quite short. Maybe four or eight? Edit: might be worthwhile to standardize on one warning period in this BIP for simplicity.

murchandamus commented at 8:32 pm on February 14, 2025:

Okay, I always use four weeks now.

Eight weeks seems excessive and since the BIPs repository is append-only anyway, we can always accommodate slow reactions.

murchandamus commented at 1:18 am on February 15, 2025: contributor

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.

murchandamus commented at 10:01 pm on February 15, 2025: contributor

I replied to @maaku here: #1712 (review)

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.

murchandamus commented at 7:57 pm on February 19, 2025: contributor

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

murchandamus force-pushed on Feb 19, 2025

ajtowns commented at 4:12 pm on February 20, 2025: contributor

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?

ACK fdc80484468c2290cf424a1270640cdbd1bc1e01 reACK c34ab2c16e31de8def0d373a87ed93e3397c9df5

glozow commented at 4:59 pm on February 20, 2025: member

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 on Feb 20, 2025

sipa commented at 7:44 pm on February 20, 2025: member

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.

in bip-0003.md:533 in c34ab2c16e outdated

528+  audience.
529+
530+#### BIP Format
531+
532+- The Standards Track type is superseded by the similar Specification type.[^standard-track]
533+- Many sections are declared optional, it is up to the authors and audience to judge whether all relevant topics have

jonatack commented at 9:17 pm on February 20, 2025:

0- Many sections are declared optional; it is up to the authors and reviewers to judge whether all relevant optional topics have

murchandamus commented at 6:20 pm on February 21, 2025:

I took the semicolon and change to “reviewers, but the additional “optional” seems unnecessary: all relevant topics have to be addressed sufficiently, regardless whether the sections are optional or not.

in bip-0003.md:648 in c34ab2c16e outdated

643+    using "Proposed" as a status field value was overloading the term: clearly _proposals_ are proposed at all stages of
644+    the process. "Complete" expresses that the authors have concluded planned work on all parts of the proposal and are
645+    ready to recommend their BIP for adoption. The term "ready" was also considered, but considered too subjective.
646+[^rejection]: **Why can proposals remain in Draft or Complete indefinitely?**  
647+    The automatic 3-year timeout of BIPs has led to some disagreement in the past and seems unnecessary in cases where
648+    the authors are still active in the community and still consider their idea worth pursuing. On the other hand,

jonatack commented at 9:23 pm on February 20, 2025:

double “still”; consider s/are still active/remain active/

murchandamus commented at 6:26 pm on February 21, 2025:

went with “remain active” + “still consider”

in bip-0003.md:649 in c34ab2c16e outdated

644+    the process. "Complete" expresses that the authors have concluded planned work on all parts of the proposal and are
645+    ready to recommend their BIP for adoption. The term "ready" was also considered, but considered too subjective.
646+[^rejection]: **Why can proposals remain in Draft or Complete indefinitely?**  
647+    The automatic 3-year timeout of BIPs has led to some disagreement in the past and seems unnecessary in cases where
648+    the authors are still active in the community and still consider their idea worth pursuing. On the other hand,
649+    Draft proposals that appear stale may be tested and cleared out after only one year which should achieve the main goal of

jonatack commented at 9:24 pm on February 20, 2025:

0    Draft proposals that appear stale may be tested and cleared out after only one year, which should achieve the main goal of

(“tested” also seems an odd word choice here)

murchandamus commented at 6:29 pm on February 21, 2025:

Changed to “Draft proposals that appear stale may be closed after only one year,…”

in bip-0003.md:653 in c34ab2c16e outdated

648+    the authors are still active in the community and still consider their idea worth pursuing. On the other hand,
649+    Draft proposals that appear stale may be tested and cleared out after only one year which should achieve the main goal of
650+    the original rule by limiting the effort and attention spent on proposals that never reach Complete.
651+[^closed]: **Why was the Closed Status introduced?**  
652+    The Closed Status provides value to the audience by indicating which documents are only of historical significance.
653+    Previously, the process had Deferred, Obsolete, Rejected, Replaced, and Withdrawn which all meant some flavor of

jonatack commented at 9:25 pm on February 20, 2025:

0    Previously, the process had Deferred, Obsolete, Rejected, Replaced, and Withdrawn, which all meant some flavor of

in bip-0003.md:654 in c34ab2c16e outdated

649+    Draft proposals that appear stale may be tested and cleared out after only one year which should achieve the main goal of
650+    the original rule by limiting the effort and attention spent on proposals that never reach Complete.
651+[^closed]: **Why was the Closed Status introduced?**  
652+    The Closed Status provides value to the audience by indicating which documents are only of historical significance.
653+    Previously, the process had Deferred, Obsolete, Rejected, Replaced, and Withdrawn which all meant some flavor of
654+    "work has stopped on this". The many statuses complicated the process, may have contributed to process fatigue, and

jonatack commented at 9:26 pm on February 20, 2025:

0    "work has stopped on this." The many statuses complicated the process, may have contributed to process fatigue, and

murchandamus commented at 6:30 pm on February 21, 2025:

How American English places punctuation around subsentences will forever seem odd to me. ^^

in bip-0003.md:506 in c34ab2c16e outdated

501+
502+The BIP editors are intended to fulfill administrative and editorial responsibilities. The BIP editors monitor BIP
503+changes, and update BIP headers as appropriate.
504+
505+BIP editors may also, at their option, unilaterally make and merge strictly editorial changes to BIPs, such as
506+correcting misspellings, fixing broken links, etc. as long as they do not change the meaning or conflict with the

jonatack commented at 9:42 pm on February 20, 2025:

0correcting misspellings/grammar, fixing broken links, etc., as long as they do not change the meaning or conflict with the

in bip-0003.md:550 in c34ab2c16e outdated

545+- Comments-URI and Comment-Summary headers are dropped from the preamble.[^comments]
546+- The "Superseded-By" header is replaced with the "Proposed-Replacement" header.
547+- The "Post-History" header is replaced with the "Discussion" header.
548+- The "Discussions-To" header is dropped as it has never been used in any BIP.
549+- Introduce Deputies and optional Deputies header.
550+- Titles may now be up to 50 characters.

jonatack commented at 9:45 pm on February 20, 2025:

0- The BIP "Title" header may now contain up to 50 characters (previously 44 in BIP 2).

in bip-0003.md:545 in c34ab2c16e outdated

540+- The distinction between recommended and acceptable licenses was dropped.
541+- Most licenses that have not been used in the BIP process have been dropped from the list of acceptable licenses.
542+
543+#### Preamble
544+
545+- Comments-URI and Comment-Summary headers are dropped from the preamble.[^comments]

jonatack commented at 9:46 pm on February 20, 2025:

This comment and the next few harmonize the style in this section; you could choose to go with no quote-wrapping instead.

0- The "Comments-URI" and "Comment-Summary" headers are dropped from the preamble.[^comments]

in bip-0003.md:549 in c34ab2c16e outdated

544+
545+- Comments-URI and Comment-Summary headers are dropped from the preamble.[^comments]
546+- The "Superseded-By" header is replaced with the "Proposed-Replacement" header.
547+- The "Post-History" header is replaced with the "Discussion" header.
548+- The "Discussions-To" header is dropped as it has never been used in any BIP.
549+- Introduce Deputies and optional Deputies header.

jonatack commented at 9:48 pm on February 20, 2025:

0- Introduce Deputies and an optional "Deputies" header.

in bip-0003.md:551 in c34ab2c16e outdated

546+- The "Superseded-By" header is replaced with the "Proposed-Replacement" header.
547+- The "Post-History" header is replaced with the "Discussion" header.
548+- The "Discussions-To" header is dropped as it has never been used in any BIP.
549+- Introduce Deputies and optional Deputies header.
550+- Titles may now be up to 50 characters.
551+- Layer header is optional for Specification BIPs or Informational BIPs, as it does not make sense for all BIPs.[^layer]

jonatack commented at 9:49 pm on February 20, 2025:

0- The "Layer" header is optional for Specification BIPs or Informational BIPs, as it does not make sense for all BIPs.[^layer]

in bip-0003.md:552 in c34ab2c16e outdated

547+- The "Post-History" header is replaced with the "Discussion" header.
548+- The "Discussions-To" header is dropped as it has never been used in any BIP.
549+- Introduce Deputies and optional Deputies header.
550+- Titles may now be up to 50 characters.
551+- Layer header is optional for Specification BIPs or Informational BIPs, as it does not make sense for all BIPs.[^layer]
552+- Rename "Author" field to "Authors".

jonatack commented at 9:50 pm on February 20, 2025:

0- Rename the "Author" field to "Authors".

in bip-0003.md:558 in c34ab2c16e outdated

553+
554+### Updates to Existing BIPs should this BIP be Activated
555+
556+#### Previous BIP Process
557+
558+This BIP supersedes BIP 2 as the guideline for the BIP process.

jonatack commented at 9:51 pm on February 20, 2025:

nit, per the new terms used here

0This BIP replaces BIP 2 as the guideline for the BIP process.

in bip-0003.md:498 in c34ab2c16e outdated

493+
494+Editors do NOT evaluate whether the proposal is likely to be adopted.
495+
496+A BIP editor will:
497+
498+* Assign a BIP number and BIP type in the pull request

jonatack commented at 9:56 pm on February 20, 2025:

I mildly wonder if people could use this section to argue that an editor must assign a number to a proposal that fulfills the list above while yet considered out of scope of the BIPs repository.

murchandamus commented at 6:17 pm on February 21, 2025:

Good point, I added “The described idea is on-topic for the repository” after the first point, and added a “Then, " before “a BIP Editor will”.

jonatack commented at 9:59 pm on February 20, 2025: member

Reviewed the new diffs and skimmed the whole document. There are still a few parts at the end that I haven’t quite looked at yet. None of these comments are blockers to a draft merge; currently the BIP author is weighing another consideration or two.

BIP3: Update BIP Process d5c189f328

murchandamus force-pushed on Feb 20, 2025

jonatack commented at 11:20 pm on February 20, 2025: member

ACK d5c189f3285baa4822c03ca312f962b16d8eb199 draft appears complete, latest push is squash-only, further improvements can be made on the road to upgrading to Proposed status

jonatack merged this on Feb 20, 2025

jonatack closed this on Feb 20, 2025

murchandamus referenced this in commit 1f9e52a0b0 on Feb 21, 2025

murchandamus commented at 6:33 pm on February 21, 2025: contributor

@jonatack Thanks for the merge. I opened a pull request to address the remaining review comments in this follow-up PR: https://github.com/bitcoin/bips/pull/1771

BIP3: Updated BIP Process #1712

Changes from BIP 2

Workflow

BIP Format

Preamble

Closed

Changes from BIP 2