Disambiguate and document the closure process

[basil]

Over the past few months and especially during Hacktoberfest, I have observed several cases where the contribution process did not go as smoothly as it could have gone. After thinking deeply about several examples, I concluded that the existing process contains ambiguities that, once disambiguated, would make the process go more smoothly in the future. In this pull request I have distilled my thoughts into a concrete process improvement. The motivation, as explained clearly in this PR, is to deliver value to end users and to encourage both new and seasoned contributors alike. In this PR I explain how this goal can be more readily achieved by disambiguating the process, and I document how an improved process would work.

Testing done

Visual inspection of the the rendered AsciiDoc to confirm there were no rendering errors.

Proposed changelog entries

N/A

Proposed upgrade guidelines

N/A

Submitter checklist

• The Jira issue, if it exists, is well-described.
• The changelog entries and upgrade guidelines are appropriate for the audience affected by the change (users or developers, depending on the change) and are in the imperative mood (see examples).
  • Fill in the Proposed upgrade guidelines section only if there are breaking changes or changes that may require extra steps from users during upgrade.
• There is automated testing or an explanation as to why this change has no tests.
• New public classes, fields, and methods are annotated with @Restricted or have @since TODO Javadocs, as appropriate.
• New deprecations are annotated with @Deprecated(since = "TODO") or @Deprecated(forRemoval = true, since = "TODO"), if applicable.
• New or substantially changed JavaScript is not defined inline and does not call eval to ease future introduction of Content Security Policy (CSP) directives (see documentation).
• For dependency updates, there are links to external changelogs and, if possible, full differentials.
• For new APIs and extension points, there is a link to at least one consumer.

Desired reviewers

@mention

Maintainer checklist

Before the changes are marked as ready-for-merge:

• There are at least two (2) approvals for the pull request and no outstanding requests for change.
• Conversations in the pull request are over, or it is explicit that a reviewer is not blocking the change.
• Changelog entries in the pull request title and/or Proposed changelog entries are accurate, human-readable, and in the imperative mood.
• Proper changelog labels are set so that the changelog can be generated automatically.
• If the change needs additional upgrade steps from users, the upgrade-guide-needed label is set and there is a Proposed upgrade guidelines section in the pull request title (see example).
• If it would make sense to backport the change to LTS, a Jira issue must exist, be a Bug or Improvement, and be labeled as lts-candidate to be considered (see query).

[lemeurherve]

Great improvement!

Since this is the only file in ./docs/, WDYT of putting it directly at the root folder of this repository?

Maybe also add a link to this doc in the PR section of CONTRIBUTING?
https://github.com/jenkinsci/jenkins/blob/master/CONTRIBUTING.md?plain=1#L148

[basil]

Thank you for the review Hervé.

Great improvement!

I am glad that these ideas resonate with at least one contributor.

Since this is the only file in ./docs/, WDYT of putting it directly at the root folder of this repository?
Maybe also add a link to this doc in the PR section of CONTRIBUTING? https://github.com/jenkinsci/jenkins/blob/master/CONTRIBUTING.md?plain=1#L148

Let me take this as an opportunity to illustrate one of the things I discuss in this PR, which is negotiating scope. I agree that having this file in /docs/ is inconsistent with other documentation and that it would make more sense at the root folder of the repository. (Another inconsistency is that some of the files are in Markdown, while others are in AsciiDoc.) And I do not see how it could hurt to add more links to MAINTAINERS from various places, including CONTRIBUTING. But all of these problems are preëxisting issues present before this PR, and I fear that increasing the scope of this PR to include them would have two effects:

• It would make this PR more difficult to review, since this PR would include both a cleanup of directory structure and formatting, as well as a substantive change to process, forcing reviewers to switch back and forth between two different logical changes
• It would risk delaying the integration of the cleanup of directory structure and formatting if discussions about the substantive change to process take a longer time

For these reasons, I would prefer to keep the scope of this PR as-is (i.e., limited to the closure process), and keep any unrelated changes to the directory structure, formatting, and linking of these documents to a separate PR, which hopefully could be reviewed very easily and integrated very quickly. While I am not personally up for filing that separate PR right this minute, I would welcome you to file it if you are interested, and if not I might get around to it eventually in a few weeks once I process more items on my TODO list.

[StefanSpieker]

I really like the idea of assigning a maintainer to a PR on which he helps getting it eventually merged. This would also help new contributers who to ask for help an their PR. So I think the clearer process can help speed up the process of working on PRs.
Furthermore the clarification of the "Negotiating scope" is well written and describes the current model quite good.
At least the parts which clarify the current progress do add a lot for newcomers, how PRs are handled within this project.

But I guess approvals, especially for the new assigne should be done by the other maintainers which are "more involved". Besides that, for the tables I would add a title, although I do not find a great one.

[basil]

Thank you for the review Stefan.

I really like the idea of assigning a maintainer to a PR on which he helps getting it eventually merged. This would also help new contributors who to ask for help an their PR. So I think the clearer process can help speed up the process of working on PRs. Furthermore the clarification of the "Negotiating scope" is well written and describes the current model quite good. At least the parts which clarify the current progress do add a lot for newcomers, how PRs are handled within this project.

I am glad that these ideas resonate with another contributor. You have understood the primary purpose of this proposal: to provide clear and explicit expectations and lines of communication between core maintainers and contributors, with the goal of a smoother integration process and therefore increased future engagement.

But I guess approvals, especially for the new assigne should be done by the other maintainers which are "more involved".

Yes of course.

Besides that, for the tables I would add a title, although I do not find a great one.

Good point. I added "Optimal Outcome" and "Suboptimal Outcome" headings to the tables.

[github-actions]

Please take a moment and address the merge conflicts of your pull request. Thanks!

[github-actions]

Please take a moment and address the merge conflicts of your pull request. Thanks!

[Wadeck]

Overall, it seems to be a pretty nice proposal. The simple fact that a PR author can have a single point of contact to help them is pretty valuable.

One fear that I have with that, is to increase the entry barrier cost for non-frequent core maintainers. If I am spending a moment of review during a WE, I don't necessarily want to invest even more time to "babysit" PRs, but I could already put some ready-for-merge labels for example. I understand the desire to ensure the promise are fulfilled related to ready-for-merge => 24h etc.
Imagine the situation where two core maintainers are reviewing a PR, one on Saturday the second on Sunday, with the "current" process the PR can be merged, but with the proposed one, none of them will be able to add the label.

No data point, I imagine it's not that often the case. Hence not a blocker at all, just wanting to see it in effect and to see the impact of that change.

[Wadeck]

Not convinced that should be part of the documentation. That could add more pressure on the people, leading to less engagement.

Inactive core maintainers will not even read that documentation ;)

[basil]

Thank you for the review Wadeck.

Overall, it seems to be a pretty nice proposal. The simple fact that a PR author can have a single point of contact to help them is pretty valuable.

Indeed. Much like #7218 set clear expectations for submissions (e.g., that authors have the responsibility to test their submissions), this PR sets clear expectations for maintainers (e.g., that maintainers have the responsibility to steer the discussion towards justified action items and to confirm that they have been completed). Setting clear expectations reduces friction and increases alignment towards a common goal: the closure of the pull request, ideally via acceptance rather than rejection!

This does not mean that we need to have a legalistic or rigid mentality. But think about the discomfort a newcomer might face not knowing what the expectations are on both sides. Having some set of common expectations takes away some of that discomfort.

Imagine the situation where two core maintainers are reviewing a PR, one on Saturday the second on Sunday, with the "current" process the PR can be merged, but with the proposed one, none of them will be able to add the label.

Yes, requiring that merges be done by the same maintainer who applied the ready-for-merge label comes with both an advantage and a disadvantage.

• The advantage is that we do not send a signal to the PR author that their submission will be merged soon when in fact there may not be a core maintainer who has committed to merging it. This is not a hypothetical scenario; rather, I observed it during Hacktoberfest this year and wanted to improve our process to avoid this suboptimal outcome.
• The disadvantage is that we lose a small degree of parallelism. Suppose 24 hours have passed since the ready-for-merge label was applied. In the old system, any other maintainer could take up the task of pressing the merge button. In the new system, this should only be done by the maintainer who applied the ready-for-merge label, who may be unable to press the merge button until the next day (e.g. because they were sleeping when the clock hit 24 hours).

The tradeoff here is best understood in terms of the correctness vs performance duality. The old system is capable of delivering the desired result in the shortest amount of time (i.e., its best-case performance is optimal), but it sometimes sends the wrong signal to authors (i.e., it sometimes lacks correctness). The new system always sends the correct signal to authors (i.e., it always has correctness) but occasionally loses a small degree of parallelism (i.e., its best-case performance is suboptimal).

Recall that my two explicit high-level goals were (1) to deliver value to end users and (2) to encourage new and existing PR authors alike. Optimizing globally for these goals motivates the tradeoff I made in favor of correctness over performance.

One fear that I have with that, is to increase the entry barrier cost for non-frequent core maintainers. If I am spending a moment of review during a WE, I don't necessarily want to invest even more time to "babysit" PRs, but I could already put some ready-for-merge labels for example. […] Not convinced that [the cautionary reminder to infrequent core maintainers] should be part of the documentation. That could add more pressure on the people, leading to less engagement.

As alluded to in the Motivation section, the current low barrier for infrequent core maintainers comes with its own disadvantages for PR authors. PR authors tend to at least hope (if not assume) that individuals with maintainer status (indicated e.g. by the green checkmark) will merge their change in a timely fashion. People coming from the corporate world (where individual contributors are typically expected to do peer reviews) are more likely to have this expectation. Infrequent core maintainers are less likely to meet this expectation, sometimes leading to confusion and frustration for PR authors. As much of a chore as it can sometimes be, shepherding PRs to completion (I prefer this phrase over "babysitting") is a key part of fostering a vibrant FOSS community. I believe it is critical for our community's future.

As with the previous example, this is a matter of tradeoffs. Recall that my two explicit high-level goals were (1) to deliver value to end users and (2) to encourage new and existing PR authors alike. Optimizing globally for these goals motivates the tradeoff I made in favor of PR authors and frequent core maintainers and against infrequent core maintainers.

Note that nobody is being asked to do any more (or less) than what they are doing today. Self-assignment is strictly voluntary. Nobody will force assignments upon others. The existing contributions of current maintainers are highly appreciated. Nobody will be asked to "step up or step down." But yes this proposal does implicitly incentivize existing active core maintainers to remain active and existing inactive core maintainers to become more active for the benefit of end users and PR authors. I am intentionally seeking to incentivize a virtuous circle, and I believe it is in the long-term best interests of our community.

Thinking more deeply about your point, I suspect your point may be more about the negative phrasing of my sentence rather than my genuine desire to incentivize a virtuous circle. Perhaps we could address your point by inverting the phrasing of the sentence in the positive direction: "In light of the responsibility to close pull requests implied by membership on the core team, all core maintainers are strongly encouraged to regularly close pull requests." What do you think?

Is there a need to add a point about when an assignee failed to invest the necessary time?

I assume you are specifically referring to the sentence "if the assignee cannot provide such confirmation in a timely fashion, the assignee should consider whether it is appropriate to remain assigned to the pull request in light of the commitment to the contributor that such an assignment implies."

I imagine that should not occur often, but with a process more and more detailed, I am wondering.

It does occur from time to time. In one case the PR author asked if it would "make more sense to give this review to another member of the core team" (their words, although my proposal was written first), which supports my notion that PR authors want an explicit point of contact. As with the previous example, I suspect your point is more about the negative phrasing of my sentence rather than my genuine desire to improve PR review outcomes. Perhaps we could address your point by inverting the phrasing of the sentence in the positive direction: "If the assignee cannot provide such confirmation in a timely fashion, the assignee should consider unassigning themselves from the pull request to allow another core maintainer to pick it up". What do you think?

I would say that this kind of "introduction" should be done in a separate PR as it's more controversial. It's related to the topic but would perhaps slow down the whole PR.

The Zen of Python says that "explicit is better than implicit" and that "in the face of ambiguity, refuse the temptation to guess." Along these lines, the section about voting goes along with the two main themes of this proposal: decreasing ambiguity and providing explicit reasoning as much as possible. This elevates the level of discourse by focusing on objective arguments over subjective opinions, and the Apache project's implementation of these concepts has been particularly useful in past discussions. To some degree I have already been employing some of these practices in my own reviews, so I did not think it would be particularly controversial. If it is, it could be split out into a separate proposal as you describe; if it is not, I think it jives with the current proposal nicely. I would like to hear what others think before going in one direction or another.

[basil]

Note that #7516 (review) was posted about a month ago and that I addressed the review feedback within four (4) hours in #7516 (comment). A month later, #7516 (comment) remains unacknowledged.

When an author's response to review feedback remains unacknowledged for an extended period of time, this sends the implicit message to the author that their contribution was not valuable. This, in turn, decreases the likelihood that the author will contribute again.

The "Speed of Code Reviews" section in Google's Engineering Practices Documentation describes what happens in situations like this:

• The velocity of the team as a whole is decreased.
• Developers start to protest the review process.
• Project health can be impacted.

For this reason, this proposal documents the expectation that maintainers reply to authors in a timely fashion.

[Wadeck]

"In light of the responsibility to close pull requests implied by membership on the core team, all core maintainers are strongly encouraged to regularly close pull requests." What do you think?

Yes a lot better 👍

---

"If the assignee cannot provide such confirmation in a timely fashion, the assignee should consider unassigning themselves from the pull request to allow another core maintainer to pick it up". What do you think?

In this case it's not the wording but more the inaction that I think is problematic. If an assignee is not active during a period of time, it's unlikely they will come back just to unassign them. Yes it's a quick action but it's more about the "mental load" implied by this.
Alternative proposal that is not requiring the active-then-inactive maintainer to respond: "If the assignee cannot provide such confirmation in a timely fashion, the contributor or another core maintainers could ask the current assignee about their intentions and in the absence of a response the PR could be unassigned by another core maintainer." WDYT?

---

(your comment was created in the meantime)

A month later

Christmas ;)

[basil]

Yes a lot better +1

Great! I have applied the new phrasing.

WDYT?

Good point; I have applied your suggestion.

Christmas ;)

This response is neither logically cogent (because of the lack of an argument) nor grammatically correct (because of the lack of a verb).

[amuniz]

Looks good to me, specially the "actionable feedback from the reviewer" part.
Thanks!

[daniel-beck]

Looks like a reasonable improvement overall and worth a try IMO. Motivation is a bit unclear as problems being solved are mentioned, but not described further.

The degree of detail and legal-like language are perhaps not ideal ways to motivate people to participate in this process, but I guess we'll see how this goes.

Similarly, many of the responsibilities of the assignee are currently shared responsibilities of the maintainers group. While explicitly stating them seems helpful in creating a common understanding, a potential unintended side effect might be that being not an assignee will be seen as having no responsibility at all, even if there's prior involvement in a PR.

[basil]

Looks like a reasonable improvement overall and worth a try IMO.

Thank you for the review, Daniel!

Motivation is a bit unclear as problems being solved are mentioned, but not described further.

I tried to strike a balance between not being descriptive enough and being too descriptive by describing the general problems I have observed without needlessly drawing attention to particular examples. I want to focus on the future and not dwell on the past.

The degree of detail and legal-like language are perhaps not ideal ways to motivate people to participate in this process, but I guess we'll see how this goes.

I would have preferred to discuss topics like this in a less formal venue, but we currently do not have e.g. a regular meeting for core maintainers.

Similarly, many of the responsibilities of the assignee are currently shared responsibilities of the maintainers group.

Indeed, and I consider this a problem because they are not shared equally.

While explicitly stating them seems helpful in creating a common understanding, a potential unintended side effect might be that being not an assignee will be seen as having no responsibility at all, even if there's prior involvement in a PR.

Today a few pull requests get a lot of attention while many pull requests get zero attention. My hope is that this proposal will spread core maintainer attention more evenly.

[daniel-beck]

But I see no forum for core maintainers where such decisions could be discussed and voted on. As I mentioned previously, we currently do not have e.g. a regular meeting for core maintainers.

Having something like that would be useful IMO.

[oleg-nenashev]

I have not been very active recently, but this PR got my attention. First of all, thanks to @basil for documenting some missing bits of the process, and for basically suggesting a new process. Most of the pull request definitely should be merged as something that improves the process documentation. Some bits de-facto change the process though

Not sure I can even count as a maintainer after a long hiatus (announced to the community), but I definitely vote -1 for any process that introduces a veto right that has no normal discussion and override process.

[basil]

All feedback up until the present time has been addressed.

Fixed in commit b7bf24d and commit a45419c

[oleg-nenashev]

Thanks for the amendments @basil ! In the current form, the text looks fine with me and it seems to outline the current process and intentions well.

[MarkEWaite]

Approved with sincere thanks for your efforts.

I reviewed the full document and found a few items that would benefit from a minor update, but none of those items are being modified in this pull request. I'll submit separate pull requests for those trivial improvements.

[basil]

This PR is now ready for merge. We will merge it after approximately 24 hours if there is no negative feedback. Please see the merge process documentation for more information about the merge process. Thanks!