Migrating to the new matplotlib codebase
========================================

Michael Droettboom has spent the last several months working on the
"transforms branch" of matplotlib, in which he rewrote from the ground
up the transformation infrastructure in matplotlib, which many found
unintuitive and hard to extend.  In addition to a cleaner code base,
the reorganization allows you to define your own transformations and
projections (e.g. map projections) within matplotlib.  He has merged his
work into the HEAD of the svn trunk, and this will be the basis for
future matplotlib releases.

If you are a svn user, we encourage you to continue using the trunk as
before, but with the understanding that you are now truly on the
bleeding edge.  Michael has made sure all the examples still pass with
the new code base, so for the vast majority of you, I expect to see
few problems.  But we need to get as many people as possible using the
new code base so we can find and fix the remaining problems.  We have
take the svn code used in the last stable release in the 0.91 series,
and made it a maintenance branch so we can still fix bugs and support
people who are not ready to migrate to the new transformation
infrastructure but nonetheless need access to svn bug fixes.

Using the new code
==================

To check out the trunk with the latest transforms changes:

    > svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/matplotlib

If you already have a working copy of the trunk, your next "svn up" will
include the latest transforms changes.  

Before installing, make sure you completely remove the old matplotlib
build and install directories, eg: 

    > cd matplotlib
    > sudo rm -rf build
    > sudo rm -rf /usr/local/lib/python2.5/site-packages/matplotlib
    > sudo python setup.py install

Using the old svn code
======================

To check out the maintenance branch, in order to commit bugfixes to 0.91.x:

    > svn co  https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/v0_91_maint  matplotlib_0_91_maint

Any applicable bugfixes on the 0.91.x maintenance branch should be
merged into the trunk so they are fixed there as well.  Svnmerge.py
makes this process rather straightforward, but you may also manually
merge if you prefer.

Merging bugfixes on the maint branch to the trunk using svnmerge.py
-------------------------------------------------------------------

Download svnmerge.py from here:

  http://www.orcaware.com/svn/wiki/Svnmerge.py

From the working copy of the *trunk* (svnmerge.py always pulls *to*
the current working copy), so

   > svnmerge.py merge

to pull in changes from the maintenance branch.  Manually resolve any
conflicts, if necessary, test them, and then commit with

   > svn commit -F svnmerge-commit-message.txt

(Note the above will stop working when the maintenance branch is
abandoned.)

API CHANGES in the new transformation infrastructure
====================================================

While Michael worked hard to keep the API mostly unchanged while
performing what has been called "open heart surgery on matplotlib",
there have been some changes, as discussed below.

The primary goal of these changes was to make it easier to
extend matplotlib to support new kinds of projections.  This is
primarily an internal improvement, and the possible user-visible
changes it allows are yet to come.

These changes are detailed in the API_CHANGES document.