csc302h: engineering large software systems

keeping your group's matplotlib repo up to date

this howto assumes that you have already read the howto on working with your group's git repo, have pulled your repo, built and run matplotlib and pushed some changes back to your repo. it is also assumed that the steps in this howto are being executed on cdf. a similar procedure may work on other systems, but this has only been tested on cdf.

initially, your group's repo was cloned from matplotlib on github. since then there have been a number of changes to the matplotlib master branch that we now want to merge with our own changes we made to our repos. this howto will guide you through the steps necessary to do this on cdf.

this howto assumes that you will be first cloning your repo to a new folder. you can pull to an existing local copy of your repo if you like, and the following steps will work, but it may result in a slightly different build directory after you have finished and built. the reason for this is that when something gets removed from the official repo on github it doesn't always get removed from a previous build's build directory. for example, matplotlib used to distribute it's own copy of dateutil, which it no longer does. if an old version of dateutil is in build it will remain there after this process. i have installed dateutil on cdf in a common location for us to use moving forward.

ok, lets get started...

clone your repo

clone your existing repo somewhere under your home directory on cdf and give it a name. in this example, we are cloning repo XXX (replace with your repo number) to a folder, that will get created, called localrepo.

> git clone https://git.cdf.toronto.edu/csc302-XXX localrepo

once the cloning process has completed, change to the directory containing your new local copy of your group's repo.

> cd localrepo

so far, so good.

merge your local repo with matplotlib's master branch on github

this is the most interesting step, and the one most likely to cause us grief when we execute the merge instruction, but more on that in a minute...

in git lingo, repositories are called "remotes". the matplotlib repository on github is no exception, so we use the remote add command to start tracking it in preparation for the merge.

> git remote add matplotlib https://github.com/matplotlib/matplotlib.git

note also that we gave it the name matplotlib so it will be easier to refer to.

now we need to "fetch" all the heads and tags from the matplotlib repo so we can merge with master. when the fetch command finishes it shows you a list of all the available branches and tags.

> git fetch matplotlib

you should now see something like this in your console:

now for the (possibly) tricky part...merging with the remote's master. type the following command to initiate the merge operation:

> git merge matplotlib/master

you will see a bunch of lines whizzing by, showing all the add/delete/merge operations that git is doing to merge your local repo with the github master branch. at the end, if you are lucky, all of the operations, including auto-merge of changed files, will complete and we are ready to move on. if you are unlucky, you will have some manual merging work to do. You will know if this is the case by having lines like this in the output:

CONFLICT (content): Merge conflict in lib/matplotlib/XXX.py
...
Automatic merge failed; fix conflicts and then commit the result.

you will see one or more of the CONFLICT lines, you may have to scroll to see them all, and you will see the line telling you the merge failed at the end. the good news is that in each of the files where the auto-merge failed (in this case, XXX.py) git puts markers showing you the location of the problem, the version in the remote repo, and the local version. as the developer, you can choose either to keep the remote version, the local version, a combination, or something totally different from either. when you are done manual merging, checkin the file to complete the merge operation. once all files are done, and you are satisfied, you can break the link to the github repo:

> git remote rm matplotlib

build & test your new matplotlib

now, lets check that it all worked. Build your new matplotlib with the following command:

> python setup.py build

once the build process is finished, you need to update your PYTHONPATH environment variable to point to your new matplotlib, and a few other python libraries installed just for us under the csc302h home directory.

> export PYTHONPATH=~csc302h/winter/pub:$PWD/build/lib.linux-x86_64-2.7

(tcsh users remember to use setenv, without the equal sign, instead of export)

now lets run one of the examples as a test:

> python -S examples/mplot3d/surface3d_demo.py

you should now be looking at the plot below.

great! now lets share it with the rest of our team...

push your newly merged local repo to your group's shared repo

this step is really easy, simply use the push command to the origin repo as you have been doing for all other changes you've made previously doing your assignments:

> git push origin master

now your other team members can clone the repo and get the new, up-to-date, version.

summary of commands

for convenience, here is a list of commands needed to merge the master branch from the matplotlib github repo with your team's repository on cdf:

> git clone https://git.cdf.toronto.edu/csc302-XXX localrepo

...replace "XXX" with your group's repository number on CDF...

> # change to the new repo directory
> cd localrepo
>
> # fetch and merge with remote master branch on github
> git remote add matplotlib https://github.com/matplotlib/matplotlib.git
> git fetch matplotlib
> git merge matplotlib/master

...manually fix anything that failed to auto-merge...

> # break the connection to the remote repo
> git remote rm matplotlib
>
> # build it
> python setup.py build
> 
> # run a test!
> export PYTHONPATH=~csc302h/winter/pub:$PWD/build/lib.linux-x86_64-2.7

(again, tcsh users omit the equal sign and use setenv instead)

> python -S examples/mplot3d/surface3d_demo.py
>
> # push local to team's repo
> git push origin master