Merging instructions

Development matplotlib-devel
1

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 git@...679...: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 git@...679...: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

2

I just wrote this as a response to a question on
Bugfix/legend windowcall by WeatherGod · Pull Request #32 · matplotlib/matplotlib · GitHub
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 git@...679...: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 git@...679...: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 git@...679...: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 03/07/2011 09:36 AM, Jouni K. Seppänen wrote:

3

Hi Jouni,

Thanks for doing this...

I just wrote this as a response to a question on
Bugfix/legend windowcall by WeatherGod · Pull Request #32 · matplotlib/matplotlib · GitHub
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 git@...679...: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 git@...679...: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

···

On Mon, Mar 7, 2011 at 2:36 PM, Jouni K. Seppänen <jks@...278...> wrote:

4

I just wrote this as a response to a question on
Bugfix/legend windowcall by WeatherGod · Pull Request #32 · matplotlib/matplotlib · GitHub
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
git@...679...: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 git@\.\.\.679\.\.\.: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 git@\.\.\.679\.\.\.: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

···

On Mon, Mar 7, 2011 at 3:14 PM, Eric Firing <efiring@...229...> wrote:

On 03/07/2011 09:36 AM, Jouni K. Seppänen wrote: