Thread: [matplotlib-devel] Merging instructions

I just wrote this as a response to a question on
https://github.com/matplotlib/matplotlib/pull/32
about how to merge to v1.0.x and master.

Please feel free to comment or ask for details.

------------------------------------------------------------------------------
First make sure your v1.0.x branch is fresh:

    git checkout v1.0.x
    git pull --ff-only upstream v1.0.x

(This assumes an "upstream" remote pointing to
`git://github.com/matplotlib/matplotlib.git`.) Then merge your pull
request and run the test suite (I don't know if this should be
mandatory):

    git merge bugfix/legend_windowcall # replace by whatever you are merging
    python setup.py install # or however you compile things to run the tests
    ./tests.py # all new test runner script!

If everything is fine, push:

    git push gi...@gi...:matplotlib/matplotlib.git v1.0.x

Next do the same with master, this time merging v1.0.x:

    git checkout master
    git pull --ff-only upstream master
    git merge v1.0.x
    python setup.py install
    ./tests.py
    git push gi...@gi...:matplotlib/matplotlib.git master
------------------------------------------------------------------------------

There are multiple ways things could go wrong, which will need
instructions in the devel docs. These are the cases I can think of:

1. git pull --ff-only fails because fast-forward is impossible
   (you have commits on an integration branch that don't belong there)
2. the merge has conflicts
3. the tests fail (also a kind of merge conflict, assuming the tests
   passed before)
4. the push fails because fast-forward is impossible (someone has 
   pushed in the meantime)
5. v1.0.x doesn't merge cleanly into master

-- 
Jouni K. Seppänen
http://www.iki.fi/jks

On 03/07/2011 09:36 AM, Jouni K. Seppänen wrote:
> I just wrote this as a response to a question on
> https://github.com/matplotlib/matplotlib/pull/32
> about how to merge to v1.0.x and master.
>
> Please feel free to comment or ask for details.
>
> ------------------------------------------------------------------------------
> First make sure your v1.0.x branch is fresh:
>
>      git checkout v1.0.x
>      git pull --ff-only upstream v1.0.x
>
> (This assumes an "upstream" remote pointing to
> `git://github.com/matplotlib/matplotlib.git`.) Then merge your pull

By default, however, if you have cloned from 
gi...@gi...:matplotlib/matplotlib.git then instead of "upstream" the 
remote will be "origin".

Are you recommending and assuming that we clone *only* from our 
individual github forks, and then add the "upstream" remote to point to 
the official repo?

> request and run the test suite (I don't know if this should be
> mandatory):
>
>      git merge bugfix/legend_windowcall # replace by whatever you are merging
>      python setup.py install # or however you compile things to run the tests
>      ./tests.py # all new test runner script!
>
> If everything is fine, push:
>
>      git push gi...@gi...:matplotlib/matplotlib.git v1.0.x

Can't this be simplified by using "origin" or "upstream" in place of the 
url?

>
> Next do the same with master, this time merging v1.0.x:
>
>      git checkout master
>      git pull --ff-only upstream master
>      git merge v1.0.x
>      python setup.py install
>      ./tests.py
>      git push gi...@gi...:matplotlib/matplotlib.git master
> ------------------------------------------------------------------------------
>
> There are multiple ways things could go wrong, which will need
> instructions in the devel docs. These are the cases I can think of:
>
> 1. git pull --ff-only fails because fast-forward is impossible
>     (you have commits on an integration branch that don't belong there)
> 2. the merge has conflicts

I encountered that last night.  The conflict was a simple one that will 
occur often: the CHANGELOG needed to have the new entry prepended, so as 
to be at the top of the file, above new entries that were in master but 
not in v1.0.x.  Instructions for simplest case:

Edit the conflicted files, remembering to remove the conflict markers;
test as needed; use "git add" to add the resolved files (and any other 
files that needed to be changed to make the merge work) to the index, e.g.

     git add CHANGELOG

Then commit; a merge commit message will be generated, and can be edited 
as needed:

     git commit

Now you are ready to push.

> 3. the tests fail (also a kind of merge conflict, assuming the tests
>     passed before)
> 4. the push fails because fast-forward is impossible (someone has
>     pushed in the meantime)
> 5. v1.0.x doesn't merge cleanly into master

What do you mean by this?  What is the symptom?

Eric

On Mon, Mar 7, 2011 at 3:14 PM, Eric Firing <ef...@ha...> wrote:
> On 03/07/2011 09:36 AM, Jouni K. Seppänen wrote:
>> I just wrote this as a response to a question on
>> https://github.com/matplotlib/matplotlib/pull/32
>> about how to merge to v1.0.x and master.
>>
>> Please feel free to comment or ask for details.
>>
>> ------------------------------------------------------------------------------
>> First make sure your v1.0.x branch is fresh:
>>
>>      git checkout v1.0.x
>>      git pull --ff-only upstream v1.0.x
>>
>> (This assumes an "upstream" remote pointing to
>> `git://github.com/matplotlib/matplotlib.git`.) Then merge your pull
>
> By default, however, if you have cloned from
> gi...@gi...:matplotlib/matplotlib.git then instead of "upstream" the
> remote will be "origin".
>
> Are you recommending and assuming that we clone *only* from our
> individual github forks, and then add the "upstream" remote to point to
> the official repo?

No, I don't think there is such an assumption. Remotes can be named
whatever you want. I've ditched the "origin/upstream" convention for
naming remotes entirely, and instead use "matplotlib", "darrendale",
etc. I think Jouni was clear: "This assumes an "upstream" remote
pointing to ..."

>> request and run the test suite (I don't know if this should be
>> mandatory):
>>
>>      git merge bugfix/legend_windowcall # replace by whatever you are merging
>>      python setup.py install # or however you compile things to run the tests
>>      ./tests.py # all new test runner script!
>>
>> If everything is fine, push:
>>
>>      git push gi...@gi...:matplotlib/matplotlib.git v1.0.x
>
> Can't this be simplified by using "origin" or "upstream" in place of the
> url?

I think it can.

>>
>> Next do the same with master, this time merging v1.0.x:
>>
>>      git checkout master
>>      git pull --ff-only upstream master
>>      git merge v1.0.x
>>      python setup.py install
>>      ./tests.py
>>      git push gi...@gi...:matplotlib/matplotlib.git master
>> ------------------------------------------------------------------------------
>>
>> There are multiple ways things could go wrong, which will need
>> instructions in the devel docs. These are the cases I can think of:
>>
>> 1. git pull --ff-only fails because fast-forward is impossible
>>     (you have commits on an integration branch that don't belong there)
>> 2. the merge has conflicts
>
> I encountered that last night.  The conflict was a simple one that will
> occur often: the CHANGELOG needed to have the new entry prepended, so as
> to be at the top of the file, above new entries that were in master but
> not in v1.0.x.  Instructions for simplest case:
>
> Edit the conflicted files, remembering to remove the conflict markers;
> test as needed; use "git add" to add the resolved files (and any other
> files that needed to be changed to make the merge work) to the index, e.g.
>
>     git add CHANGELOG
>
> Then commit; a merge commit message will be generated, and can be edited
> as needed:
>
>     git commit
>
> Now you are ready to push.
>
>> 3. the tests fail (also a kind of merge conflict, assuming the tests
>>     passed before)
>> 4. the push fails because fast-forward is impossible (someone has
>>     pushed in the meantime)
>> 5. v1.0.x doesn't merge cleanly into master
>
> What do you mean by this?  What is the symptom?

The master branch may have changed such that the same lines of code
have been edited in different ways along the master and v1.0.x
branches of development.

Darren

Eric Firing <ef...@ha...> writes:

>>      git pull --ff-only upstream v1.0.x
>>
>> (This assumes an "upstream" remote pointing to
>> `git://github.com/matplotlib/matplotlib.git`.) Then merge your pull
>
> By default, however, if you have cloned from 
> gi...@gi...:matplotlib/matplotlib.git then instead of "upstream" the 
> remote will be "origin".
>
> Are you recommending and assuming that we clone *only* from our 
> individual github forks, and then add the "upstream" remote to point to 
> the official repo?

I was assuming that, based on the github instructions:

http://help.github.com/fork-a-repo/

But of course there are many ways to do it. We'll have to decide what we
like best and stick to it in the manual; I personally don't have any
strong opinions on what to call the various repositories. Perhaps
"origin" for the central repository and "public" for your own github
repo (as in the public counterpart of your private development repo)?

>> If everything is fine, push:
>>
>>      git push gi...@gi...:matplotlib/matplotlib.git v1.0.x
>
> Can't this be simplified by using "origin" or "upstream" in place of the 
> url?

Yes, if that's the read-write address. If you cloned from the read-only
address, you can't push to it.

>> 2. the merge has conflicts
>
> I encountered that last night.  The conflict was a simple one that will 
> occur often: the CHANGELOG needed to have the new entry prepended,

Oh, of course. That's going to occur a lot.

>> 5. v1.0.x doesn't merge cleanly into master
>
> What do you mean by this?  What is the symptom?

A merge conflict or (probably much less often) a test failure, because
v1.0.x and master have diverged in the relevant part. An example is pull
request #17, which modifies make.osx:

https://github.com/matplotlib/matplotlib/pull/17

But make.osx has changed in master, so while merging this request will
not have a merge conflict (at least with current v1.0.x), merging to
master will. I created another pull request that includes this one and
resolves the merge conflict:

https://github.com/matplotlib/matplotlib/pull/30

So when #17 is merged into v1.0.x, #30 should be merged into master.

-- 
Jouni K. Seppänen
http://www.iki.fi/jks

On 03/07/2011 10:30 AM, Jouni K. Seppänen wrote:

>>> 5. v1.0.x doesn't merge cleanly into master
>>
>> What do you mean by this?  What is the symptom?
>
> A merge conflict or (probably much less often) a test failure, because
> v1.0.x and master have diverged in the relevant part. An example is pull
> request #17, which modifies make.osx:
>
> https://github.com/matplotlib/matplotlib/pull/17

This brings up something that confuses me, together with related 
questions, and so might be another topic for this part of the docs:

1) How is it that you were able to add commits to a branch of someone 
else's fork?

2) How should it be decided who merges a pull request, and when?

3) Under what circumstances, if any, should a pull request involving 
multiple commits be collapsed into a single changeset prior to being 
merged and pushed?

Eric


>
> But make.osx has changed in master, so while merging this request will
> not have a merge conflict (at least with current v1.0.x), merging to
> master will. I created another pull request that includes this one and
> resolves the merge conflict:
>
> https://github.com/matplotlib/matplotlib/pull/30
>
> So when #17 is merged into v1.0.x, #30 should be merged into master.
>

Eric Firing <ef...@ha...> writes:

>> https://github.com/matplotlib/matplotlib/pull/17
>
> This brings up something that confuses me, together with related 
> questions, and so might be another topic for this part of the docs:
>
> 1) How is it that you were able to add commits to a branch of someone 
> else's fork?

I sent Fernando a pull request:

https://github.com/fgb/matplotlib/pull/1

He merged my commits to his branch, and his pull request was
automatically updated.

> 2) How should it be decided who merges a pull request, and when?

I think John called for not too much bureaucracy - before git we were
committing things without any review. On the other hand, with git there
is less urgency to get things into master, since if you need someone's
bugfix or feature to continue developing your own stuff, you can pull
from their branch into your own. I think we can depend on everyone's
good judgment.

If we need a guideline, my suggestion is that if someone other than the
author reviews the code and says it is good, or if no-one raises any
issues for some time, it can be merged.

If there are merge conflicts, usually the person who wrote the code is
in the best position to resolve them.

> 3) Under what circumstances, if any, should a pull request involving 
> multiple commits be collapsed into a single changeset prior to being 
> merged and pushed?

If we had a strict policy that tests must pass for every revision (which
I don't think we have had) it would make sense to squash multiple
commits into one if the intermediate commits don't pass the test
suite. Squashing is an instance of a rebase operation, so it should be
avoided for any commits on which someone may have based further work.

-- 
Jouni K. Seppänen
http://www.iki.fi/jks

Hi Jouni,

Thanks for doing this...

On Mon, Mar 7, 2011 at 2:36 PM, Jouni K. Seppänen <jk...@ik...> wrote:
> I just wrote this as a response to a question on
> https://github.com/matplotlib/matplotlib/pull/32
> about how to merge to v1.0.x and master.
>
> Please feel free to comment or ask for details.
>
> ------------------------------------------------------------------------------
> First make sure your v1.0.x branch is fresh:
>
>    git checkout v1.0.x
>    git pull --ff-only upstream v1.0.x
>
> (This assumes an "upstream" remote pointing to
> `git://github.com/matplotlib/matplotlib.git`.) Then merge your pull
> request and run the test suite (I don't know if this should be
> mandatory):
>
>    git merge bugfix/legend_windowcall # replace by whatever you are merging
>    python setup.py install # or however you compile things to run the tests
>    ./tests.py # all new test runner script!
>
> If everything is fine, push:
>
>    git push gi...@gi...:matplotlib/matplotlib.git v1.0.x
>
> Next do the same with master, this time merging v1.0.x:
>
>    git checkout master
>    git pull --ff-only upstream master
>    git merge v1.0.x
>    python setup.py install
>    ./tests.py
>    git push gi...@gi...:matplotlib/matplotlib.git master

We might also want to mention the special case of what needs to be
done for a change not intended for merging into master.

> ------------------------------------------------------------------------------

No comments, it's just the way I would have recommended it.

> There are multiple ways things could go wrong, which will need
> instructions in the devel docs. These are the cases I can think of:
>
> 1. git pull --ff-only fails because fast-forward is impossible
>   (you have commits on an integration branch that don't belong there)

Right, and we should emphasize that integration branches (like master
and v1.0.x) in your local repo should only ever get ahead of the
remote repo for the few moments between merging a branch and pushing
back up to the remote.

> 2. the merge has conflicts
> 3. the tests fail (also a kind of merge conflict, assuming the tests
>   passed before)
> 4. the push fails because fast-forward is impossible (someone has
>   pushed in the meantime)
> 5. v1.0.x doesn't merge cleanly into master

Nicely summarized.

Darren