[IPython-dev] Tips on merging: the green button is good...

[Fernando Perez]

Hi folks,

I just wanted to mention some things regarding workflow that we kind
of settled on in the 0.12 merge frenzy but that we haven't really said
explicitly in a summary.  A while ago, I had defended the idea that we
should allow fast-forward merges and even force them via a rebase for
really small PRs of one or two commits; my argument was that this kept
a more linear and clean history, without adding 'unnecessary' commits.
 But in the run-up to 0.12, Mateusz and Min talked about it and Min
came back with some good points in favor of *always, exclusively*
doing merges with the green button.

The main point is that by doing the merge with the green button, we
gain evidence for what code was reviewed and what wasn't.  When a
merge is done that way, the merge commit has a link to the review
right there, that is even clickable in github.  This way, even single
commits that were reviewed can be distinguished from commits that were
pushed without review.  In the long run, this information is useful to
the project, and in fact shows a flaw in my original argument.  I said
that the extra merge commit was 'noise', but in reality that extra
commit is data: it links to the *review* of the commit(s) being
merged, and so it's in fact very important data and certainly not
noise.

Furthermore, we gain:

- the PR is automatically closed, which otherwise doesn't always happen.

- it's super easy to type into the merge message a summary of the PR,
b/c you can copy straight out from either the initial PR request or
from relevant pieces of the discussion.

So the workflow we had settled on, and that I hope you will all agree with, was:

- *Always* merge from the 'green button'.

- When doing the merge, add a reasonable summary of the PR in the
message box, don't just leave it empty.  A good tip is to click on
'edit' at the top in the PR request message, so you can copy/paste the
whole Markdown of the PR.  That text is typically a good starting
point for the commit message, though I typically trim it down or
rephrase it slightly so it's a good summary of the PR.

- At the bottom of the merge message, add 'Closes #NNN, closes #NNN'
as appropriate for any tickets this PR has been confirmed to close.
This way, github will auto-close them reliably.

That's it.  Once I got used to this, it became very natural.  I use
'git mrb' to test locally, then I simply merge the PR with the green
button and issue 'git pull' right away.  Since git already has all the
actual commits, the pull is very quick.

Cheers,

f