[IPython-dev] Pull request workflow...

[Fernando Perez]

Hi Darren,

I'm bouncing back this reply to the list, because this is a good
question that deserves clarification.  I'm hoping in the end, this
conversation will be summarized in our guidelines, so I'd rather have
it all publicly archived.

On Sun, Oct 10, 2010 at 5:43 PM, Darren Dale <dsdale24 at gmail.com> wrote:

> I should thank you for putting me onto git at scipy 2009. Its an
> amazing tool, I don't want to work with anything else.

Glad you've liked it!  I have to admit that back then, it was mostly a
hunch based on liking its abstract design a lot and early
experimentation, but I didn't really have too much hands-on experience
with complex tasks yet (mostly handling very linear repos only).  Now
that I've used it 'in rage' for a while, I really, really love it :)

>> If you absolutely need to merge something from trunk (because it has
>> fixes you need for your own work), then rebase on top of trunk before
>> making your pull request, so that your branch applies cleanly on top
>> of trunk as a self-contained unit without criss-crossing.
>
> I'm seeking clarification concerning your comments on pull request
> workflow. I'm not working with pull requests as intimately as you are,
> and some of your comments really surprised me. I thought it was bad
> practice to rebase on a branch that was published anywhere, because if
> anyone else is tracking that branch, it makes an unholy mess of the
> history in their local checkout. Rebasing actually replays the changes
> on a new reference point, and anyone else who has made changes on the
> old reference point will be out for blood.
>
> I thought the right thing to do was to merge from master before filing
> a pull request. I can see that this would yield some diamonds in the
> history graph, but it minimizes the deltas while avoiding the problems
> inherent in rebasing on a public branch, especially on a complicated
> branch with multiple contributors.

Good question. The way I see it, feature branches proposed for
inclusion should never be considered 'stable' in the sense of anyone
following them and building on top of them.  In that case, the cleaner
history for merge into trunk trumps other considerations, I think.
The problem is that the merges lead to more than simple diamonds: they
spread the history of the branch all over the place.

I should note that even if the proposer doesn't rebase, they still
have to contend with the possibility that the reviewer may rebase upon
merging, just like I did with Thomas' py3-preparation branch. I did it
to give us a much cleaner history and a cleanly grouped view of his
work (otherwise the merge had created a *massive* amount of lines in
the DAG, because he had merged multiple times from trunk).

So in this case, even though I didn't touch the contents of any of
Thomas' commits, he will still discard his local branch and pull from
trunk, so that he can have the official version of the history (same
contents and timestamps, different SHAs, because of my rebase).

The approach I propose depends on one idea and assumption: that the
branches aren't terribly long-lived, and that there isn't a
complicated hierarchy of branches-from-branches.  It encourages the
development of small, self-contained feature branches.

Note that the above doesn't preclude anyone from benefiting from a
given feature branch and the history in trunk: they can use their
master, or any other integration branch, where they track trunk and
merge the feature *into*.  This branch will be their personal way of
tracking trunk and using their feature (or features, this can be done
with multiple branches) until the feature is merged upstream.  In fact
I have done this multiple times already, and it works fine.

Does this sound reasonable?  I'm no git expert though, so it's quite
possible there are still cases I haven't considered or where the above
is insufficient.  We'll have to find the patterns that fit them as we
encounter them.

Cheers,

f