RFR: Section on PRs [v2]

[Roger Riggs]

On Thu, 7 Apr 2022 18:45:09 GMT, Phil Race <prr at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Added sentence about keeping PR up to date
>
> src/index.md line 1473:
> 
>> 1471: 
>> 1472:    The description of the PR should state what problem is being solved and shortly describe how it's solved. Reviewers and other interested readers are referred to the text in the JBS issue for details, but the description should be enough to give an overview.
>> 1473: 
> 
> This means the JBS issue should have an evaluation so you may want to explicitly say so.

Mostly the above test covers it. Remembering that the description is included in many emails.

Two things bug me about some PR descriptions; those that are too long and too short.
The too long ones I've seen can Include extensive performance before/after information.
They should be added in a separate comment after the description.
The too short ones are the lazy ones that just refer to the bugid.

I'm not sure where to suggest notes to this effect are inserted.

I'd also prefer to see PRs that are complete when they are created.
Code changes, test additions, copyrights updated, all done.
It is annoying to see a dribble of minor updates and accompanying emails
while the developer works through their own thought processes.
And even updating minor changes due to comments should be batched.
But this may be a developer style issue, to each their own, but why should I witness every change.

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

PR: https://git.openjdk.java.net/guide/pull/79