An updated BIP Process

[murchandamus]

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.

[LarryRuane]

Suggested change

	authors. A shepherds may perform the role of an Author for any aspect of the BIP process unless overruled by an Author.
	authors. A Shepherd may perform the role of an Author for any aspect of the BIP process unless overruled by an Author.

I'm suggesting "a Shepherd" so it matches the plurality of "an Author".

[LarryRuane]

Suggested change

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

[murchandamus]

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.

[sipa]

This looks great. Just a few nits.

[sipa]

Should "Bitcoin community" not be capitalized?

[murchandamus]

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.

[sipa]

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]

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.

[LarryRuane]

Suggested change

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

[murchandamus]

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

[LarryRuane]

Suggested change

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

[murchandamus]

See above

[achow101]

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]

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]

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.

[achow101]

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]

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.

[murchandamus]

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

[murchandamus]

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.

[murchandamus]

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

[murchandamus]

See above

[murchandamus]

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.

[murchandamus]

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

[murchandamus]

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.

[murchandamus]

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.

[murchandamus]

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]

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.

[jonatack]

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

[murchandamus]

Replaced with "?" for the time being.

[jonatack]

Here and throughout this document.

Suggested change

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

[murchandamus]

I had just changed that the other way per request of @real-or-random here: murchandamus#2 (comment). How about you two discuss here? ^^

[jonatack]

Suggested change

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

[jonatack]

Suggested change

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

[murchandamus]

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

[murchandamus]

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

[jonatack]

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]

Okay, folded this section into "What is a BIP?"

[katesalazar]

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

[EthanHeilman]

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

[murchandamus]

No strong reasons. I changed it to black.

[murchandamus]

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

[murchandamus]

Replaced with "?" for the time being.

[murchandamus]

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.

[murchandamus]

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

[murchandamus]

Okay, folded this section into "What is a BIP?"

[murchandamus]

No strong reasons. I changed it to black.

[JeremyRubin]

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.