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

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

murchandamus force-pushed on Dec 10, 2024

Draft an updated BIP Process 9e472b8877

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

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.

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:

Fix minor issues from review 2043128284

Set "?" as date before number assignment 83e2df4427

Let Authors update the README table entry 722b523d7a

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.

Allow Changelog in Draft bf44183568

Capitalize the concept, system, and idea Bitcoin 27ddfa6568

Drop bit about continuation lines f52a0c0621

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.

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

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

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

Fix minor issues from review 7966c39542

Fold section on repo scope into "What is a BIP?" 61cbe9d416

Change color of Closed state to black in diagram d6e4b5a2ae

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.

An updated BIP Process #1712