RFR: Section on PRs [v2]

[Pavel Rappo]

On Wed, 6 Apr 2022 19:25:48 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Some tips for creating pull requests.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Added sentence about keeping PR up to date

There is also something to be said on rebasing in particular, aside from the fact that it "disrupts the workflow for reviewers". Let me try to outline the idea.

In my limited experience, one problem with rebasing is that it has potential to silently invalidate author's assumptions on the state of the repo at the base of the PR. And while problems caused by this are usually detected for the head commit of the PR, it is not the case for other commits that comprise the PR. It's especially so if those commits have detailed messages which reviewers are expected to read.

In an ideal world, if the base changes, the author should update the PR commit by commit [^1] to carefully propagate the effects of this change; almost like they were doing it anew. The author should ensure that each commit passes tests and that its message is up to date. Oherwise those who review their work might be left scratching their head trying to correlate the commit message with that commit's content.

Don't get me wrong; I'm not saying that rebasing is bad. Rebasing is useful and has its place. But generally that place is "before the PR has been published".

We provide this information. Commiters make an informed decision.

[^1]: In some sense it's a recursive task, because each PR commit other than head is the base for the remainder of the PR.

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

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