[WIP] Minimal MAINTAINERS.md file

JeremyRubin commented at 6:08 pm on August 13, 2022: contributor

This PR “reverse builds on” #25560 by carving out the parts that should be uncontroversial/purely descriptive of the current role of maintainership, while allowing #25560 to focus on the more aspirational parts (as suggested by instagibbs). Please be sure to cross reference for comments/discussion on #25560.

Add a minimal MAINTAINERS.md file and desribe the current role of maintainer more directly, to be clarified/defined in further PRs. 87fb345c13

JeremyRubin force-pushed on Aug 13, 2022

DrahtBot commented at 2:09 am on August 14, 2022: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

No conflicts as of last run.

in CONTRIBUTING.md:13 in 87fb345c13 outdated

 9@@ -10,9 +10,10 @@ First, in terms of structure, there is no particular concept of "Bitcoin Core
10 developers" in the sense of privileged people. Open source often naturally
11 revolves around a meritocracy where contributors earn trust from the developer
12 community over time. Nevertheless, some hierarchy is necessary for practical
13-purposes. As such, there are repository maintainers who are responsible for
14-merging pull requests, the [release cycle](/doc/release-process.md), and
15-moderation.
16+purposes. As such, there are repository [maintainers](/MAINTAINERS.md) who are

jarolrod commented at 2:36 am on August 17, 2022:

why link to MAINTAINERS.md twice here?

JeremyRubin commented at 8:46 pm on August 18, 2022:

i guess it is redundant? can remove, i just default to linking to where terms are defined, and separately to where more can be read.

instagibbs commented at 9:00 pm on August 18, 2022: member

thanks :) will go through

in MAINTAINERS.md:31 in 87fb345c13 outdated

26+repository, and connotes a general sense of stewardship over the project.
27+
28+
29+Largely, the role of maintainers is to decide to merge Pull Requests.
30+
31+Whether a pull request is merged into Bitcoin Core rests with the project merge

mzumsande commented at 9:04 pm on August 18, 2022:

This sentence is basically identical to the one before. Suggest to drop one of them.

JeremyRubin commented at 3:52 pm on August 29, 2022:

they say different things:

Scoping that is what a maintainer is
text ripped from CONTRIBUTING.md, which clarifies how a maintainer makes that decision.

maybe the 1st can become:

0Largely, the role of maintainers is to merge Pull Requests when appropriate.

in MAINTAINERS.md:93 in 87fb345c13 outdated

88+## Maintainer Prioritizations
89+
90+While the maintainers are ultimately not accountable to any particular roadmap,
91+nor can make regular contributors focus on one area or another, practically the
92+views and prioritizations of maintainers have an impact on what gets reviewed,
93+merged, and the general direction of the project.

mzumsande commented at 9:12 pm on August 18, 2022:

This is very debatable, see #25560 (review) with which I agree. I would prefer to remove it.

JeremyRubin commented at 3:55 pm on August 29, 2022:

Removing it would seem to me be prescriptive (aspirational), rather than descriptive of the current status quo. We should aim to debate prescriptive additions or omissions in follow up work?

in MAINTAINERS.md:11 in 87fb345c13 outdated

 6+
 7+## Current Maintainers
 8+
 9+The current maintainers are:
10+
11+| Name  | Focus Areas |

maflcko commented at 8:04 am on August 19, 2022:

Pretty sure I already left a comment about this in the other pull, but I don’t see the the point of a focus area column. The focus area is something that is entrusted to the maintainer to decide for themselves. If they can’t do that, they shouldn’t become a maintainer in the first place.

Also, the focus area may constantly change. For example I no longer care about functional tests as much as I did 5 years ago, because they are in a much better shape by now. Am I supposed to remove myself from that focus area now? Also, achow recently merged a p2p change in commit 22d96d76ab02fc73e7fe0d810bacee4c982df085, so is someone supposed to edit this table before or after the fact? Finally, if all rows mention “general” I wonder what the point is, since the conveyed information is minimal if not none.

JeremyRubin commented at 3:16 pm on August 19, 2022:

I responded on this topic in the other PR ICYMI: #25560 (review)

Not every maintainer has General tag here. For example, @hebasto and @achow101 do not. It’s up to them if they want to update it to list General or not.

If you don’t care about the test system as much these days, and don’t want to review the work there, it is no issue to update your focus areas. Doing so may also even help highlight if that area is under-maintained, and could maybe use a new maintainer.

W.r.t. @achow101 merging a P2P change, as noted in the document, these are not enforced rules, just documentation. If @achow101 plans to regularly work on P2P, I would think he should update his focus area, if it is one-off or infrequent maybe not.

Perhaps it would be nice to pair with this table a list of all “focus tags” / systems, regardless of if there is a maintainer currently focusing on it?

maflcko commented at 3:33 pm on August 19, 2022:

The details here will be effectively useless the more broad (Assume my focus area is tests, but someone creates a test for macOS, which I may not be able to review or test) they are and the less often they are updated. I can promise you that this list won’t be updated, just like no one updated REVIEWERS.md.

instagibbs commented at 3:35 pm on August 19, 2022:

Have to agree. I’d be surprised if it even gets promptly updated when maintainers join/depart.

JeremyRubin commented at 4:15 pm on August 29, 2022:

Is there a lighter touch way that can be done?

in MAINTAINERS.md:74 in 87fb345c13 outdated

69+merges.
70+
71+
72+## Nomination and Selection of Maintainers
73+
74+Being a Maintainer is not an honor (but it may be honorable to serve as one).

mzumsande commented at 3:30 pm on August 19, 2022:

Whether something is an honor is very subjective, I would not mention “honor” here at all.

JeremyRubin commented at 3:59 pm on August 29, 2022:

see discussion here. #25560 (review)

the intent is to provide clarity from the project against past statements by maintainers describing it as an honour, and honour is used in this sentence precisely to clarify that it is not an honor is the objective sense of the word (an honor, like an award / recognition).

The subjective part is up to “but it may be honorable to serve as one”.

in MAINTAINERS.md:56 in 87fb345c13 outdated

51+currently an explicit designation (all maintainers should be considered to be
52+general at this time). As a rough measure, scoped maintainers should avoid
53+"stepping on the toes" of work that is being guided by another maintainer or
54+contributor.
55+
56+Historically, one Bitcoin's maintainers was a designated "Lead Maintainer",

mzumsande commented at 3:46 pm on August 19, 2022:

This section is (or will very soon be?) out of date, maybe just mention that there used to be a lead maintainer but currently there is none. No need to elaborate on the reasons and background too much.

Rspigler commented at 8:58 pm on August 21, 2022:

0Historically, one of Bitcoin's maintainers was a designated "Lead Maintainer",

JeremyRubin commented at 4:02 pm on August 29, 2022:

I think it is good to leave in because people may want to know who the lead maintainer is, given that other documentation and sources (even those in our own repo still) refer to lead maintainer.

Leaving it out would be a disservice to a reader who wants to know who the lead is.

Of course, now that Wladimir has actually stepped down without naming a replacement, the verbiage here could be updated to have less background information because the situation is less confusing.

mzumsande commented at 3:49 pm on August 19, 2022: contributor

Concept ACK

Since opinions will always differ on a topic like this, I think a Maintainers.md file should be as bland and boring as possible, just stating the undisputable facts, nothing interpretational. The style of this document is too essayistic for my taste, some examples below.

in MAINTAINERS.md:42 in 87fb345c13 outdated

37+establishes general consensus is detailed in
38+[CONTRIBUTING.mg](/CONTRIBUTING.md).
39+
40+Thus maintainers role is not directly elevated above that of regular
41+contributors, as maintainers serve mostly as arbiters of if changes are
42+acceptable to the contributors to the project in aggregate.

Rspigler commented at 8:56 pm on August 21, 2022:

0Thus maintainers' role is not directly elevated above that of regular
1contributors, as maintainers serve mostly as arbiters of if changes are
2acceptable to the contributors of the project in aggregate.

in MAINTAINERS.md:61 in 87fb345c13 outdated

56+Historically, one Bitcoin's maintainers was a designated "Lead Maintainer",
57+which was most recently @laanwj. However, [in a blog
58+post](https://laanwj.github.io/2021/01/21/decentralize.html), @laanwj stated
59+that they wanted to take more of a background role as a maintainer and have not
60+"passed the baton" to a successor as a Lead Maintainer, and instead focused on
61+decentralizing the maintainership ecosystem. As such, while the unofficial

Rspigler commented at 9:10 pm on August 21, 2022:

0post](https://laanwj.github.io/2021/01/21/decentralize.html), [@laanwj](/bitcoin-bitcoin/contributor/laanwj/) stated
1that they wanted to take more of a background role as a maintainer, and therefore have decided not to "pass the baton" to a successor as a Lead Maintainer, instead choosing to focus on decentralizing the maintainership ecosystem. As such, while the unofficial

JeremyRubin commented at 4:17 pm on August 29, 2022:

probably removing this section now that Wlad has more fully stepped down.

in MAINTAINERS.md:69 in 87fb345c13 outdated

64+other General Maintainers, and may be explicitly deprecated in the future.
65+
66+## Self Merges
67+
68+There is no prohibition or process that differentiates self-merges from normal
69+merges.

Rspigler commented at 9:11 pm on August 21, 2022:

If there is no prohibition or process, why include this? Or maybe include why there isn’t?

JeremyRubin commented at 4:25 pm on August 29, 2022:

It is here because it is a question that has come up often, so it is good to be able to point to a documented procedure when the question arises next.

squashme: fix incorrect posessive by @ rspigler

Co-authored-by: Robert Spigler <RSpigler@ProtonMail.ch>

d595207e6e

squashme: fix missing preposition @ rspigler

Co-authored-by: Robert Spigler <RSpigler@ProtonMail.ch>

a786a67c41

squashme: improve grammar @ rspigler

Co-authored-by: Robert Spigler <RSpigler@ProtonMail.ch>

f606bec230

in CONTRIBUTING.md:318 in 87fb345c13 outdated

313@@ -319,6 +314,9 @@ be different, one should be prepared to expend more time and effort than for
314 other kinds of patches because of increased peer review and consensus building
315 requirements.
316 
317+Maintainers fulfil the role of evaluating PRs having met the above conditions
318+and merging, as detailed in [MAINTAINERS.md](/MAINTAINERS.md).

Rspigler commented at 9:15 pm on August 21, 2022:

0Maintainers fulfill the role of evaluating and merging PRs that have met the above conditions, as detailed in [MAINTAINERS.md](/MAINTAINERS.md).

JeremyRubin commented at 5:56 pm on October 2, 2022: contributor

doesn’t seem like there is desire to improve documentation here, closing / up for grabs.

JeremyRubin closed this on Oct 2, 2022

bitcoin deleted a comment on Oct 2, 2022

Rspigler commented at 8:39 pm on October 2, 2022: contributor

Please mark up for grabs, thanks

JeremyRubin added the label Up for grabs on Oct 2, 2022

maflcko added the label Docs on Oct 3, 2022

fanquake removed the label Up for grabs on Jan 11, 2023

bitcoin locked this on Jan 11, 2024

[WIP] Minimal MAINTAINERS.md file #25839

Conflicts