Site/contributing: add recommendations for working with PRs

[snazy]

This change updates the PR guidelines on the "Contributing" web page after this discussion.

[eric-maynard]

Is this a best practice? When reviewing, I really dislike when people have done this because it makes it harder to see the changes since I last reviewed, or even the difference between two states of the change.

[snazy]

This is about "Opening" a PR, no?

[eric-maynard]

My question stands, not sure how critical this step is. Smaller incremental commits is generally a good thing IMO.

[snazy]

@eric-maynard this is to get to better messages. If you do it in another way but provide good PR + Git-merge-commit summary/description that's fine, too.
Also I don't understand your argument about reviews - again - this paragraph is about opening the PR - there's nothing else you could review before, right?

[eric-maynard]

If this is to get better messages, then I'll just point to the other comment chain about using the PR description.

If this is about reviewability, I maintain that more commits is usually a good thing.

[keithgchapman]

Would it make sense to update the sentence from

"Before opening a pull request, squash all commits in your branch into a single commit"

to

"Before opening a pull request, squash commits in your branch into a few (or single) meaningful commits"

[RussellSpitzer]

I'm also not sure why we would want to require a single commit. I'd probably just drop this line and just require that folks add a meaningful summary in the PR summary.

[snazy]

It's meant as a "tip" - moved the controversial one to a separated "Tips" section.

[adnanhemani]

Question here: should we be doing Squash-and-Merges when merging code in? I'm assuming that would help with some of these issues like the changelogs - but in that case, the PR title and description still needs to be set correctly by the PR author.

[snazy]

Question here: should we be doing Squash-and-Merges when merging code in? I'm assuming that would help with some of these issues like the changelogs - but in that case, the PR title and description still needs to be set correctly by the PR author.

We've decided very early on that we want to have no merge-commits.

[eric-maynard]

Most changes LGTM, but some of the ideas here were not discussed in the mailing list and it seems that we may be able to reconfigure the repo to loosen some of the requirements around commit messages

[snazy]

Most changes LGTM, but some of the ideas here were not discussed in the mailing list and it seems that we may be able to reconfigure the repo to loosen some of the requirements around commit messages

The justification is missing concrete pointers. Also requesting another change pushed into this change, which is clearly out of scope of this PR.

[RussellSpitzer]

Do we need this rule? I'm not sure we discussed it on the thread and I'd like to minimize the number of rules a newcomer to the project has to follow.

[snazy]

It's also rather a tip. We had a few occurrences where PRs were in "ready for review" but were actually "work in progress" or "superseded" or "paused". Moved this to a separate "Tips" section.

[snazy]

Hi @eric-maynard, the controversial sections in this PR have been addressed. Can you please take a look at them, review the changes, and reassess your -1

[eric-maynard]

Looks good now, thanks for improving the CONTRIBUTING guide like this

[snazy]

Thx! Merged.