Revision: 6585
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6585&view=rev
Author: mdboom
Date: 2008-12-12 13:34:06 +0000 (Fri, 12 Dec 2008)
Log Message:
-----------
Cleanup svnmerge docs; add Andrew's git docs
Modified Paths:
--------------
branches/v0_98_5_maint/doc/devel/coding_guide.rst
branches/v0_98_5_maint/doc/faq/installing_faq.rst
Modified: branches/v0_98_5_maint/doc/devel/coding_guide.rst
===================================================================
--- branches/v0_98_5_maint/doc/devel/coding_guide.rst 2008-12-12 13:26:48 UTC
(rev 6584)
+++ branches/v0_98_5_maint/doc/devel/coding_guide.rst 2008-12-12 13:34:06 UTC
(rev 6585)
@@ -9,6 +9,8 @@
Version control
===============
+.. _using-svn:
+
svn checkouts
-------------
@@ -52,7 +54,7 @@
* Can you pass :file:`examples/tests/backend_driver.py`? This is our
poor man's unit test.
-* Can you add a test to file:`unit/nose_tests.py` to test your changes?
+* Can you add a test to :file:`unit/nose_tests.py` to test your changes?
* If you have altered extension code, do you pass
:file:`unit/memleak_hawaii.py`?
@@ -68,6 +70,170 @@
<http://www.orcaware.com/svn/wiki/Svnmerge.py>`_ to keep them in
sync. See :ref:`svn-merge` below.
+.. _svn-merge:
+
+Using svnmerge
+--------------
+
+svnmerge is useful for making bugfixes to a maintenance branch, and
+then bringing those changes into the trunk.
+
+The basic procedure is:
+
+* install ``svnmerge.py`` in your PATH::
+
+ > wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/\
+ svnmerge/svnmerge.py
+
+* get a svn checkout of the branch you'll be making bugfixes to and
+ the trunk (see above)
+
+* Create and commit the bugfix on the branch.
+
+* Then make sure you svn upped on the trunk and have no local
+ modifications, and then from your checkout of the svn trunk do::
+
+ svnmerge.py merge -S BRANCHNAME
+
+ Where BRANCHNAME is the name of the branch to merge *from*,
+ e.g. v0_98_5_maint.
+
+ If you wish to merge only specific revisions (in an unusual
+ situation), do::
+
+ > svnmerge.py merge -rNNN1-NNN2
+
+ where the ``NNN`` are the revision numbers. Ranges are also
+ acceptable.
+
+ The merge may have found some conflicts (code that must be manually
+ resolved). Correct those conflicts, build matplotlib and test your
+ choices. If you have resolved any conflicts, you can let svn clean
+ up the conflict files for you::
+
+ > svn -R resolved .
+
+ ``svnmerge.py`` automatically creates a file containing the commit
+ messages, so you are ready to make the commit::
+
+ > svn commit -F svnmerge-commit-message.txt
+
+Setting up svnmerge
+~~~~~~~~~~~~~~~~~~~
+
+.. note::
+ The following applies only to release managers when there is
+ a new release. Most developers will not have to concern themselves
+ with this.
+
+* Creating a new branch from the trunk (if the release version is
+ 0.98.5 at revision 6573)::
+
+ > svn copy \
+ https://matplotlib.svn.sf.net/svnroot/matplotlib/trunk/matplot...@6573 \
+ https://matplotlib.svn.sf.net/svnroot/matplotlib/branches/v0_98_5_maint \
+ -m "Creating maintenance branch for 0.98.5"
+
+* You can add a new branch for the trunk to "track" using
+ "svnmerge.py init", e.g., from a working copy of the trunk::
+
+ > svnmerge.py init
https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/v0_98_5_maint
+ property 'svnmerge-integrated' set on '.'
+
+ After doing a "svn commit" on this, this merge tracking is available
+ to everyone, so there's no need for anyone else to do the "svnmerge
+ init".
+
+* Tracking can later be removed with the "svnmerge.py uninit" command,
+ e.g.::
+
+ > svnmerge.py -S v0_9_5_maint uninit
+
+.. _using-git:
+
+Using git
+---------
+
+Some matplotlib developers are experimenting with using git on top of
+the subversion repository. Developers are not required to use git, as
+subversion will remain the canonical central repository for the
+foreseeable future.
+
+Cloning the git mirror
+~~~~~~~~~~~~~~~~~~~~~~
+
+There is an experimental `matplotlib github mirror`_ of the subversion
+repository. To make a local clone of it in the directory ``mpl.git``,
+enter the following commands::
+
+ # This will create your copy in the mpl.git directory
+ git clone git://github.com/astraw/matplotlib.git mpl.git
+ cd mpl.git
+ git config --add remote.origin.fetch +refs/remotes/*:refs/remotes/*
+ git fetch
+ git svn init --trunk=trunk/matplotlib --tags=tags
https://matplotlib.svn.sourceforge.net/svnroot/matplotlib
+
+ # Now just get the latest svn revisions from the SourceForge SVN repository
+ git svn fetch -r 6300:HEAD
+
+.. _matplotlib github mirror: http://github.com/astraw/matplotlib
+
+To install from this cloned repository, use the commands in the
+:ref:`svn installation <install-svn>` section::
+
+ > cd mpl.git
+ > python setup.py install
+
+Using git
+~~~~~~~~~
+
+The following is a suggested workflow for git/git-svn.
+
+Start with a virgin tree in sync with the svn trunk on the git branch
+"master"::
+
+ git checkout master
+ git svn rebase
+
+To create a new, local branch called "whizbang-branch"::
+
+ git checkout -b whizbang-branch
+
+Do make commits to the local branch::
+
+ # hack on a bunch of files
+ git add bunch of files
+ git commit -m "modified a bunch of files"
+ # repeat this as necessary
+
+Now, go back to the master branch and append the history of your branch
+to the master branch, which will end up as the svn trunk::
+
+ git checkout master
+ git svn rebase # Ensure we have most recent svn
+ git rebase whizbang-branch # Append whizbang changes to master branch
+ git svn dcommit -n # Check that this will apply to svn
+ git svn dcommit # Actually apply to svn
+
+Finally, you may want to continue working on your whizbang-branch, so
+rebase it to the new master::
+
+ git checkout whizbang-branch
+ git rebase master
+
+A note about git write access
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The matplotlib developers need to figure out if there should be write
+access to the git repository. This implies using the personal URL
+(``[email protected]:astraw/matplotlib.git``) rather than the public URL
+(``git://github.com/astraw/matplotlib.git``) for the
+repository. However, doing so may make life complicated in the sense
+that then there are two writeable matplotlib repositories, which must
+be synced to prevent divergence. This is probably not an
+insurmountable problem, but it is a problem that the developers should
+reach a consensus about. Watch this space...
+
.. _style-guide:
Style guide
@@ -352,84 +518,7 @@
> python simple_plot.py -d module://my_backend
-.. _svn-merge:
-Using svn-merge
-================
-
-The basic procedure is:
-
-* install ``svnmerge.py`` in your PATH::
-
- > wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/\
- svnmerge/svnmerge.py
-
-* get a svn copy of the maintenance branch and the trunk (see above)
-
-* Michael advises making the change on the branch and committing it.
- Make sure you svn upped on the trunk and have no local
- modifications, and then from the svn trunk do::
-
- svnmerge.py merge
-
- If you wish to merge only specific revisions (in an unusual
- situation), do::
-
- > svnmerge.py merge -rNNN1-NNN2
-
- where the ``NNN`` are the revision numbers. Ranges are also
- acceptable.
-
- The merge may have found some conflicts (code that must be manually
- resolved). Correct those conflicts, build matplotlib and test your
- choices. If you have resolved any conflicts, you can let svn clean
- up the conflict files for you::
-
- > svn -R resolved .
-
- ``svnmerge.py`` automatically creates a file containing the commit
- messages, so you are ready to make the commit::
-
- > svn commit -F svnmerge-commit-message.txt
-
-
-* You can add a new branch for the trunk to "track" using
- "svnmerge.py init", e.g., from a working copy of the trunk::
-
- > svnmerge.py init
https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/v0_98_4_maint
- property 'svnmerge-integrated' set on '.'
-
- After doing a "svn commit" on this, this merge tracking is available
- to everyone, so there's no need for anyone else to do the "svnmerge
- init". I'll go ahead and commit this now.
-
- Now, the trunk is tracking two branches for merges, 0.91.x and
- 0.98.4. This means that when doing a merge, one must manually
- specify which branch to merge from using the "-S" parameter. You
- can see which branches are available for merge using "svnmerge.py
- avail"::
-
- > svnmerge.py avail
- svnmerge: multiple sources found. Explicit source argument
(-S/--source) required.
- The merge sources available are:
- /branches/v0_91_maint
- /branches/v0_98_4_maint
-
- So to merge from 0.98.4, one would type::
-
- > svnmerge.py --source v0_98_4_maint merge
-
- (rather than the "svnmerge.py merge" we used to do).
-
-* The tracking for 0.98.4 can be removed with the "svnmerge.py
- uninit" command, e.g.::
-
- > svnmerge.py --source v0_9_4_maint uninit
-
- This will make merging slightly easier, (since the -S parameter is
- not required), and it is generally good practice in the long run to
- not keep extra branches lying around.
-
.. _license-discussion:
Licenses
Modified: branches/v0_98_5_maint/doc/faq/installing_faq.rst
===================================================================
--- branches/v0_98_5_maint/doc/faq/installing_faq.rst 2008-12-12 13:26:48 UTC
(rev 6584)
+++ branches/v0_98_5_maint/doc/faq/installing_faq.rst 2008-12-12 13:34:06 UTC
(rev 6585)
@@ -95,7 +95,7 @@
.. _install-svn:
Install from svn
-========================
+================
Checking out the main source::
@@ -106,53 +106,13 @@
> cd matplotlib
> python setup.py install
+For more information on Subversion usage, see :ref:`using-svn`.
+
Install from git
================
-There is an experimental `matplotlib github mirror`_ of the subversion
-repository. To make a local clone of it in the directory ``mpl.git``,
-enter the following commands::
+See :ref:`using-git`.
- # This will create your copy in the mpl.git directory
- git clone git://github.com/astraw/matplotlib.git mpl.git
- cd mpl.git
- git config --add remote.origin.fetch +refs/remotes/*:refs/remotes/*
- git fetch
- git svn init --trunk=trunk/matplotlib --tags=tags
https://matplotlib.svn.sourceforge.net/svnroot/matplotlib
-
- # Now just get the latest svn revisions from the SourceForge SVN repository
- git svn fetch -r 6300:HEAD
-
-.. _matplotlib github mirror: http://github.com/astraw/matplotlib
-
-To install from this cloned repository, use the commands in the
-:ref:`svn installation <install-svn>` section.
-
-To update your git repository with the latest svn updates from SourceForge::
-
- git svn rebase
-
-To list what changes will be committed to svn::
-
- git svn dcommit -n
-
-To commit your changes to svn::
-
- git svn dcommit
-
-A note about git write access
------------------------------
-
-The matplotlib developers need to figure out if there should be write
-access to the git repository. This implies using the personal URL
-(``[email protected]:astraw/matplotlib.git``) rather than the public URL
-(``git://github.com/astraw/matplotlib.git``) for the
-repository. However, doing so may make life complicated in the sense
-that then there are two writeable matplotlib repositories, which must
-be synced to prevent divergence. This is probably not an
-insurmountable problem, but it is a problem that the developers should
-reach a consensus about. Watch this space...
-
Backends
========
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
SF.Net email is Sponsored by MIX09, March 18-20, 2009 in Las Vegas, Nevada.
The future of the web can't happen without you. Join us at MIX09 to help
pave the way to the Next Web now. Learn more and register at
http://ad.doubleclick.net/clk;208669438;13503038;i?http://2009.visitmix.com/
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
