Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Updated docs to refer to git #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Updated docs to refer to git #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b940899
DOC - added gitwash directory using gitwash_dumper.py
jarrodmillman Feb 19, 2011
94cdae9
DOC - changed most references to svn to git
jarrodmillman Feb 19, 2011
071b769
Merge branch 'svn2git'
jarrodmillman Feb 19, 2011
7e55c11
DOC - replaced mistaken reference to ipython with matplotlib
jarrodmillman Feb 19, 2011
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,12 +36,12 @@ build_osx105:


jdh_doc_snapshot:
svn up;\
git checkout;\
python setup.py install --prefix=~/dev;\
cd doc;\
rm -rf build;\
python make.py clean;\
svn up;\
git checkout;\
python make.py html latex sf sfpdf;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we going to have to make changes to the make doc commands such as "sf" and "sfpdf"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. But they don't have to be addressed in this round of changes, since for the time being the webpage is still being hosted at sourceforge.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that "git checkout" makes any sense here; it will just print some message. "svn up" is the rough equivalent of "git pull git://github.com/matplotlib/matplotlib.git master" at least if you have the master branch checked out.



Expand Down
2 changes: 1 addition & 1 deletion doc/_templates/indexsidebar.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h3>Need help?</h3>
but it is a good idea to ping us on the mailing list too.</p>

<p>For details on what's new, see the detailed <a href="{{
pathto('_static/CHANGELOG', 1) }}">changelog</a> or browse the <a href="http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/">source code</a>. Anything that could
pathto('_static/CHANGELOG', 1) }}">changelog</a> or browse the <a href="https://github.com/matplotlib/matplotlib">source code</a>. Anything that could
require changes to your existing codes is logged in the <a href="{{
pathto('api/api_changes.html', 1) }}">api changes</a> file.</p>

Expand Down
282 changes: 37 additions & 245 deletions doc/devel/coding_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,42 @@
Coding guide
************

.. _version-control:
.. _building_source:

Version control
===============

.. _using-svn:
Building from source code
-------------------------

svn checkouts
-------------
Developers should look through the
:ref:`development quickstart <development-quickstart>`
documentation. There you will find information on building NIPY, the
required software packages and our developer guidelines.

Checking out everything in the trunk (matplotlib and toolkits)::
If you are primarily interested in using NIPY, download the source
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIPY is a neuroimaging package. How did it get here?

tarball and follow these instructions for building. The installation
process is similar to other Python packages so it will be familiar if
you have Python experience.

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk \
matplotlib --username=youruser --password=yourpass
Unpack the source tarball and change into the source directory. Once in the
source directory, you can build the neuroimaging package using::

Checking out the main source::
python setup.py build

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/\
matplotlib mpl --username=youruser --password=yourpass
To install, simply do::

sudo python setup.py install

Branch checkouts, eg the 1.0.x maintenance branch::
.. note::

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/\
v1_0_maint mpl1 --username=youruser --password=yourpass
As with any Python_ installation, this will install the modules
in your system Python_ *site-packages* directory (which is why you
need *sudo*). Many of us prefer to install development packages in a
local directory so as to leave the system python alone. This is
mearly a preference, nothing will go wrong if you install using the
*sudo* method. To install in a local directory, use the **--prefix**
option. For example, if you created a ``local`` directory in your
home directory, you would install nipy like this::

python setup.py install --prefix=$HOME/local
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even easier to just do "--user", although that might just be for setupegg.py...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was added, when, in python-2.6? We should discuss which python versions will be supported by future versions of matplotlib, but on the development mailing list

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it was added in python 2.5, but I have nothing definitive on that. In any case, I believe we are still supposed to support python 2.4



Committing changes
Expand Down Expand Up @@ -61,228 +72,9 @@ in mind.
distribution of the mpl build.

* Keep the maintenance branch (0.91) the latest release branch (eg
0.98.4) and trunk in sync where it makes sense. If there is a bug
on both that needs fixing, use `svnmerge.py
<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.apache.org/repos/asf/subversion/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. v1_0_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:

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
1.0 at revision 8503)::

> svn copy \
https://matplotlib.svn.sf.net/svnroot/matplotlib/trunk/matplotlib@8503 \
https://matplotlib.svn.sf.net/svnroot/matplotlib/branches/v1_0_maint \
-m "Creating maintenance branch for 1.0"

* 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/v1_0_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 v1_0_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 ``matplotlib``,
enter the following commands::

# Download the entire git repository into "matplotlib", name the source repository "svn".
git clone --origin svn [email protected]:astraw/matplotlib.git

# Change into the newly created git repository.
cd matplotlib

# Setup the subversion mirroring.
git svn init --trunk=trunk/matplotlib --prefix=svn/ https://matplotlib.svn.sourceforge.net/svnroot/matplotlib

# Tell git svn to analyze the subversion history
git svn rebase -l

.. _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 matplotlib
> python setup.py install

Note that it is not possible to interact with the matplotlib
maintenance branches through git due to different representations of
source code repositories in svnmerge and git.

An example git workflow
~~~~~~~~~~~~~~~~~~~~~~~

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
"trunk"::

git checkout trunk
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 trunk branch and append the history of your branch
to the git trunk branch, which will end up as the svn trunk::

git checkout trunk
git svn rebase # Ensure we have most recent svn
git rebase whizbang-branch # Append whizbang changes to trunk 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 trunk::

git checkout whizbang-branch
git rebase trunk

How was this git mirror set up?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These are notes for those interested in mirroring a subversion
repository on github. I pieced this together by lots of
trial-and-error.

Step 1: Create a local mirror of the svn repository

::

rsync -avzP rsync://matplotlib.svn.sourceforge.net/svn/matplotlib/ matplotlib-svn-rsync/

Step 2: Import the svn history into a new git repository

::

#!/bin/bash
set -e

TARGET=mpl.git.fixed
GIT=/home/astraw/git/bin/git
TRUNKBRANCH=trunk
SVNBRANCHPREFIX="svn/"

rm -rf $TARGET
mkdir $TARGET
cd $TARGET

$GIT init
$GIT svn init --rewrite-root=https://matplotlib.svn.sourceforge.net/svnroot/matplotlib \
--trunk=trunk/matplotlib --prefix=$SVNBRANCHPREFIX file:///mnt/workdisk/tmp/matplotlib-svn-rsync
$GIT svn fetch

# now, make master branch track ${SVNBRANCHPREFIX}trunk
$GIT checkout master -b tmp
$GIT branch -d master
$GIT checkout ${SVNBRANCHPREFIX}trunk -b $TRUNKBRANCH
$GIT branch -D tmp
$GIT svn rebase -l

Step 3: Upload the git repository to github

::

#!/bin/bash
set -e

TARGET=mpl.git.fixed
GIT=/home/astraw/git/bin/git
TRUNKBRANCH=trunk
SVNBRANCHPREFIX="svn/"

cd $TARGET
0.98.4) and trunk in sync where it makes sense.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this needs to be elaborated upon. It is possible to arrange merging in many ways, but one simple way would be to always merge feature branches to the oldest relevant branch first, then that branch into any newer branches. I.e. if we have a "v1.0.x" maintenance branch and a "master" development branch, and there is a bugfix that we want to apply to v1.0.x, we would merge it first into v1.0.x and then v1.0.x into master. I think this corresponds to the old svnmerge.py based workflow and to the recommendation at http://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html.

It is also possible to merge bugfix branches separately into maintenance and development branches as in http://nvie.com/posts/a-successful-git-branching-model/ but I think that requires more care in tracking that the fixes really get applied on every branch they need to.



$GIT remote add github [email protected]:astraw/matplotlib.git
git push github $TRUNKBRANCH:master

.. _style-guide:

Expand Down Expand Up @@ -353,7 +145,7 @@ use `reindent.py
<http://svn.python.org/projects/doctools/trunk/utils/reindent.py>`_ as
a command-line script. Unless you are sure your editor always
does the right thing, please use reindent.py before checking changes into
svn.
git.

Keep docstrings_ uniformly indented as in the example below, with
nothing to the left of the triple quotes. The
Expand All @@ -367,7 +159,7 @@ It may be preferable to use a temporary variable to replace a single
long line with two shorter and more readable lines.

Please do not commit lines with trailing white space, as it causes
noise in svn diffs. Tell your editor to strip whitespace from line
noise in git diffs. Tell your editor to strip whitespace from line
ends when saving a file. If you are an emacs user, the following in
your ``.emacs`` will cause emacs to strip trailing white space upon
saving for python, C and C++:
Expand Down Expand Up @@ -582,22 +374,22 @@ generated when the website it built to show up both in the `examples
website. Many people find these examples from the website, and do not
have ready access to the file:`examples` directory in which they
reside. Thus any example data that is required for the example should
be provided through the sample_data svn directory, which can then be
be provided through the sample_data git directory, which can then be
accessed using :func:`matplotlib.cbook.get_sample_data`. First get a
copy of the repository and svn add your data::
copy of the repository and git add your data::

svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/sample_data
git clone https://github.com/matplotlib/sample_data.git
cp ~/path/to/mydata.dat sample_data/
cd sample_data
svn add mydata.dat
svn commit -m 'added my data'
git add mydata.dat
git commit -m 'added my data'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"svn commit" pushes the changes into the centralized repository; "git commit" only commits them locally. The instructions should include a "git push" command, or instructions to make a pull request (depending on our policy for the sample_data repository).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, it seems get_sample_data in cbook.py has not been updated to use the git repository. I can do that in another pull request.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Jouni, save your effort. I already took care of it in pull request #2


and then in your example code you can load it into a file handle with::

import matplotlib.cbook as cbook
fh = cbook.get_sample_data('mydata.dat')

The file will be fetched from the svn repo using urllib and updated
The file will be fetched from the git repo using urllib and updated
when the revision number changes.


Expand Down
2 changes: 1 addition & 1 deletion doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ little differently. These figures are not to be generated during the
documentation build, in order to keep the prerequisites to the documentation
effort as low as possible. Please run the :file:`doc/pyplots/make.py` script
when adding such figures, and commit the script **and** the images to
svn. Please also add a line to the README in doc/pyplots for any additional
git. Please also add a line to the README in doc/pyplots for any additional
requirements necessary to generate a new figure. Once these steps have been
taken, these figures can be included in the usual way::

Expand Down
Binary file added doc/devel/gitwash/branch_list.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/devel/gitwash/branch_list_compare.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading