BIP 3 and issues on BIPs

[Anthony Towns]

From bips#2175: https://github.com/bitcoin/bips/pull/2175#issuecomment-4550089883

> > Lastly, the BIPs repo does not have an Issues tab. An Issues tab would
> > allow for discussion of such things without opening a demonstrative PR.
> (There may be other reasons, but one hypothesis amongst the BIP editors
> as to why there is no Issues tab, was that the idea was to have those
> discussions take place on the mailing list.)

(Presumably, there was also the BIPs wiki for comments about BIPs,
though that's no longer encouraged as of BIP 3)

I think not having some "centralised" place for finding previous
discussions/feedback about a BIP is a flaw in BIP 3 as it stands --
searching across bitcoin-dev, delving, stacker.news, twitter, nostr,
random blogs, etc is certainly possible, but it would be nicer if that
were a fallback, rather than the only option.

I think there's basically three classes of feedback:

1) feedback that the BIP author(s) agree is a concern, but haven't
figured out how to address

2) feedback that the BIP author(s) strongly disagree with, but that
is considered a reasonable concern more broadly

3) feedback that is mostly dismissed as trolling and not taken seriously
outside of a very small group

I wonder if it would be feasible to include the first two sorts of
feedback directly in the BIPs repo, making it much easier to find.

For example, class 1 feedback could be added directly to the affected BIP
with the agreement of the author(s), under a new top-level "Unresolved
issues" section or similar. (Issues that are "resolved" can presumably
be addressed more directly in the BIP, eg under the "Rationale" section)

Presumably, BIPs that have an "Unresolved issues" section would not
progress to "Complete".

Class 2 feedback, where the BIP *editors* agree it's a reasonable concern,
despite the *author(s)* NACKing it, could be placed under a dedicated
BIP for class-2 feedback across the repo that's maintained by the BIP
editors, perhaps as bip-xxxx/feedback-bip-yyyy.md. I guess bip-xxxx
could actually just be bip-0003.

Hopefully editors would be able to do a fairly quick/easy private vote to
make decisions here, just a call on "is this worth surfacing to everyone
or is it better left on whoever's blog?" rather than "do I agree with
this criticism or not?".

Both these types of feedback could then be refined over time to their
best version by filing PRs on the bips repo. And just as bips themselves
can have "Discussion" links, feedback items (whether class 1 or 2) could
also have links to broader/more-detailed discussion of the feedback on
mailing lists / blog posts / etc.

I think this would be a substantial improvement on the state of the art
for things like BIP 39 and its "Unanimously discourage for implementation"
criticisms, or, eg, creating issues against bitcoin-inquisition/bitcoin
[0], or commenting on old, closed PRs [1].

[0] https://github.com/bitcoin-inquisition/bitcoin/issues/74
[1] https://github.com/bitcoin/bips/pull/682#issuecomment-4503369974

Class 3 feedback, where both the BIP authors and the BIP editor group
don't think it's valuable to surface, would still have to be raised
externally and found by web searches.

(For class 2 feedback where the people complaining also have a solution
in mind that the BIP authors have rejected, the obvious solution is to
create a new BIP aimed at replacing the existing BIP)

Cheers,
aj

[Murch]

Hi AJ,

AJ wrote: > 1) feedback that the BIP author(s) agree is a concern, but

haven't figured out how to address > 2) feedback that the BIP author(s)
strongly disagree with, but that is considered a reasonable concern more
broadly > 3) feedback that is mostly dismissed as trolling and not taken
seriously outside of a very small group > I wonder if it would be
feasible to include the first two sorts of feedback directly in the BIPs
repo, making it much easier to find.

We removed the Comment system, because it had vanishing adoption and
resulted in the few submitted comments having an overstated
representation in the criticized document’s preamble. Due to the lack
of  authentication, wiki content was also often low quality and
occasionally defaced. BIP3 already recommends that the Rationale should
record relevant objections or important concerns that were raised and
addressed as this proposal was developed. Open issues are also already
often recorded in Draft BIPs. We now allow linking to multiple relevant
discussions—new threads should be added as a document matures. In an
ideal world this would already cover at least the first two classes of
feedback.

In principle I am open to the idea to collect a summary of the
discussion and dissent in a dedicated space, but there was hardly any
commentary even when anyone could post it without any friction. Why
should we expect this more arduous approach to have more adoption than
the comment system? My expectation would be that going via pull requests
and curation would not create more commentary, but the same amount of
commentary would increase work and decision making for the BIP Editors,
especially if the expectation is that BIP Editors collect such feedback
for BIPs when the authors or dissenters do not submit it.

The mailing list seems like a fine place for these discussions. It seems
to me that they receive a good amount of visibility there. If someone
observes that BIP authors have insufficiently documented issues and
concerns in their documents, this should be raised in relevant PRs or on
the mailing list—just as it e.g., was recently done for BIP54 which led
to improvements of Motivation and Rationale of BIP54.

> I think this would be a substantial improvement on the state of the
art for things like BIP 39 and its "Unanimously discourage for

implementation" criticisms,[…]

This issue has already been addressed. When BIP3 was deployed, I removed
all Comment URL headers that linked to empty wikis, and only left those
that had content. BIP3 empowers¹ BIP Owners to decide whether to remove
or keep Comment Summary and Comment URL from their BIPs. To be fair,
this information may need to be spread more broadly.

> […] or, eg, creating issues against bitcoin-inquisition/bitcoin [0], or commenting on old, closed PRs [1].

The latter was my mistake. I should have just emailed BIP authors
directly instead of commenting on the ancient PRs that submitted the
corresponding documents, or opened up a PR to propose the changes to get
the authors’ input on them.

¹ https://github.com/bitcoin/bips/blob/master/bip-0003.md#comments

Cheers,
Murch

[Anthony Towns]

On Thu, May 28, 2026 at 11:28:49AM -0700, Murch wrote:
> BIP3
> already recommends that the Rationale should record relevant objections or
> important concerns that were raised and addressed as this proposal was
> developed.

Right, I'm particularly referring to issues that aren't (sufficiently)
addressed here.

If it helps, consider the user story: "As a BIP author, if there's a
problem/concern with my (draft) BIP that I don't currently know how
to address (or perhaps don't currently have time to address), how
should I track that concern and ensure that it's known to potential
collaborators/implementers?"

My previous best answer for APO was "file an issue against
bitcoin-inquisition/bitcoin" which doesn't feel very satisfactory.

> Open issues are also already often recorded in Draft BIPs.

Can you point to some examples? That sounds like a match for what I was
thinking. ("git grep -i open.issue" in the master branch has no hits,
afaics)

> We now
> allow linking to multiple relevant discussions—new threads should be added
> as a document matures. In an ideal world this would already cover at least
> the first two classes of feedback.

I think there probably should be a second space for issues that the
author disputes; that may happen due to the criticisms being invalid,
or the author being unreasonable -- having a third party being able to
make a "yeah, this is a reasonable thing for people to be aware of"
without compromising the "BIPs are owned by their authors" principle
would be valuable.

> In principle I am open to the idea to collect a summary of the discussion
> and dissent in a dedicated space, but there was hardly any commentary even
> when anyone could post it without any friction.

From my perspective, the comments wiki wasn't valuable for either
summaries (it just contains random people's hot-takes on the topic) or
for discussion (there's not a wide range of people responding to issues).
So the friction there is just "reading/commenting is a complete waste
of time".

A list of open issues that the author agrees are worth paying attention to
in their own BIP would be worth paying attention to, I think, except for
the "oh, the game theory optimal approach is to reject all open issues;
that way more people will think my BIP is perfect" flaw.

> Why should we expect this
> more arduous approach to have more adoption than the comment system? My
> expectation would be that going via pull requests and curation would not
> create more commentary, but the same amount of commentary would increase
> work and decision making for the BIP Editors, especially if the expectation
> is that BIP Editors collect such feedback for BIPs when the authors or
> dissenters do not submit it.

I think the purpose would be to summarise commentary, not generate it. For
example, if you wanted to know "what are the concerns people have with
BIP 119 so I can judge them for myself", how would you get that answer?
Or, if you asked an AI, how would it generate a good answer? I think
the only real approach is to scour the archives of this list, delving,
optech, various pull requests, and maybe also IRC logs or twitter debates
or podcast or talk transcripts?

> > I think this would be a substantial improvement on the state of the art
> > for things like BIP 39 and its "Unanimously discourage for implementation"
> > criticisms,[…]
> This issue has already been addressed. When BIP3 was deployed, I removed all
> Comment URL headers that linked to empty wikis, and only left those that had
> content. BIP3 empowers¹ BIP Owners to decide whether to remove or keep
> Comment Summary and Comment URL from their BIPs. To be fair, this
> information may need to be spread more broadly.

Hmm, filed as https://github.com/bitcoin/bips/pull/2184 maybe.

> > […] or, eg, creating issues against bitcoin-inquisition/bitcoin [0], or commenting on old, closed PRs [1].
> The latter was my mistake. I should have just emailed BIP authors directly
> instead of commenting on the ancient PRs that submitted the corresponding
> documents, or opened up a PR to propose the changes to get the authors’
> input on them.

That wasn't meant as a criticism; just trying to figure out something
better to do in future.

Cheers,
aj

[Murch]

Hi AJ,

I get the concern that in the case of the BIP Owners disagreeing with
critics about a raised issue or whether it has been addressed
satisfactorily, the issue may not be recorded in a manner that the
critics would consider comprehensive.

Maybe directly starting with the summaries would work better than
gathering comments from random people, but given the low participation
in the repository I’m still not convinced that there would be
significant interest in contributing to these summaries. So, I’m still
convinced that it would most likely become an additional burden for the
BIP Editors to collect, curate, and referee these submissions, and would
probably still be slanted to the opinions of a few active participants
like in the prior system.

I agree that needing to dig through so many different sources sucks and
a better system would be better. I’m not sure that just having the BIP
Editors curate submissions is enough.

I’m gonna mull more on this and would be curious what others have to say.

Murch

[Murch]

I meant to, but forgot to reply to the the “Draft BIPs record open
issues” part:
I double-checked and realized that I have to retract that. While there
are a number of hits on “todo” and “tbd” across the published BIPs,
those almost exclusively refer to deferred test vectors, reference
implementations, or activation parameters. There are just a few
references to other things, mostly some data to be backfilled in
Rationale or similar. Maybe I had seen some of that in unpublished BIPs,
but you were right that open issues are not recorded in the manner that
you suggested.

-Murch