RFR: Get agreement before PR

[Magnus Ihse Bursie]

On Wed, 7 May 2025 09:21:55 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> src/guide/contributing-to-an-open-jdk-project.md line 61:
>> 
>>> 59: Once the OCA is signed, please restrain your urge to create a PR just a little while longer. In order to prepare the community for your patch, please socialize your idea on the relevant [mailing lists]. Almost all changes, and in particular any API changes, must go this route and have a broad agreement in place before there is any point in presenting code. To understand the criteria by which your patch is going to be judged, please read [Why is My Change Rejected?] below. In short, hidden constraints and assumptions, stability and quality, maintainability, compatibility, and conformance to specifications must be considered before your PR is ready to be submitted. If you don't understand the constraints for acceptance, you might be surprised when your PR is rejected.
>>> 60: 
>>> 61: Please note that lack of engagement should not be interpreted as supporting the proposal. Lack of engagement might be better interpreted as people are busy or maybe that the problem isn't compelling or high priority enough to spend time on right now. If you didn't get the desired attention and the required agreement in your mail thread, **do not** proceed to create a PR.
>> 
>> By all due respect, but that wording effectively would have prevented *lots* of actually merged and appreciated PRs in the past -- even and in particular those from the core team members themselves, who often are *just few* people, acting on Gentleman's Agreement but not by "broad" agreement. In particular for smaller, well-understood fixes, there typically is no "broad" agreement, but "silent agreement", as everybody is fine with a fix. Hence, we should not stop ourselves *unless needed*. A discussion is fine *and needed* **for API changes**. A discussion *before showing code* for small fixes makes no sense at all and makes things overly complex, as how would you discuss whether it is fine to fix a code line without showing that codeline?
>
> I think you may be over reading this.  When someone sends mail with a proposal for some feature or API then there is no obligation for anyone to respond. Lack of a timely response should not be interpreted as agreement with the proposal. The phrase "The absence of dissent is not the presence of consent" comes to mind. It may be annoying to not get a timely response from maintainers in specific areas but this shouldn't mean it's time to create a PR and start reviewing code and changes.  Code first and "code is king" may be how many projects work but here, and especially for APIs, the code will often have negative value because it distracts from the bigger questions.
> 
> One thing that has kinda worked on a few occasions is where a PR is created with an API and no implementation code, the intention being to focus on the API and avoid the distraction of folks trying to micro optimize before it's clear whether the proposal will get traction.

Maybe the text in the guide should be more clear that changes can sit anywhere on a long scale from "trivial one-line bug fixes" to "suggestions of entirely new APIs", and that this newly added comment applies to changes on the heavier side of this scale, rather than the lighter and trivial fixes. 

For these, I agree with @mkarg that it might be better just to present a PR (especially if there already exists a JBS issue with a clear specification of what is wrong) than to clog the mailing lists with unnecessary discussion about the merits of such a fix. 

Where to draw the line then is the big question... The guide can certainly ask people to rather err on the side of socializing the idea first, rather than publishing PRs.

-------------

PR Review Comment: https://git.openjdk.org/guide/pull/150#discussion_r2077392705