diff --git a/Makefile b/Makefile index cc476446ed3d..b48774742e1e 100644 --- a/Makefile +++ b/Makefile @@ -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; diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 11bf6def4722..59531123ab9f 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -64,7 +64,7 @@

Need help?

but it is a good idea to ping us on the mailing list too.

For details on what's new, see the detailed changelog or browse the source code. Anything that could +pathto('_static/CHANGELOG', 1) }}">changelog or browse the source code. Anything that could require changes to your existing codes is logged in the api changes file.

diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst index 3a1181996f95..2ea8da05ee3c 100644 --- a/doc/devel/coding_guide.rst +++ b/doc/devel/coding_guide.rst @@ -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 ` +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 +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 Committing changes @@ -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 - `_ 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 git@github.com: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 ` 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. + - $GIT remote add github git@github.com:astraw/matplotlib.git - git push github $TRUNKBRANCH:master .. _style-guide: @@ -353,7 +145,7 @@ use `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 @@ -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++: @@ -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' 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. diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 08c3e6eab953..cfd82b4d68b4 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -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:: diff --git a/doc/devel/gitwash/branch_list.png b/doc/devel/gitwash/branch_list.png new file mode 100644 index 000000000000..1196eb754d36 Binary files /dev/null and b/doc/devel/gitwash/branch_list.png differ diff --git a/doc/devel/gitwash/branch_list_compare.png b/doc/devel/gitwash/branch_list_compare.png new file mode 100644 index 000000000000..336afa374604 Binary files /dev/null and b/doc/devel/gitwash/branch_list_compare.png differ diff --git a/doc/devel/gitwash/configure_git.rst b/doc/devel/gitwash/configure_git.rst new file mode 100644 index 000000000000..df0071902e79 --- /dev/null +++ b/doc/devel/gitwash/configure_git.rst @@ -0,0 +1,123 @@ +.. _configure-git: + +=============== + Configure git +=============== + +.. _git-config-basic: + +Overview +======== + +Your personal git_ configurations are saved in the ``.gitconfig`` file in +your home directory. +Here is an example ``.gitconfig`` file:: + + [user] + name = Your Name + email = you@yourdomain.example.com + + [alias] + ci = commit -a + co = checkout + st = status -a + stat = status -a + br = branch + wdiff = diff --color-words + + [core] + editor = vim + + [merge] + summary = true + +You can edit this file directly or you can use the ``git config --global`` +command:: + + git config --global user.name "Your Name" + git config --global user.email you@yourdomain.example.com + git config --global alias.ci "commit -a" + git config --global alias.co checkout + git config --global alias.st "status -a" + git config --global alias.stat "status -a" + git config --global alias.br branch + git config --global alias.wdiff "diff --color-words" + git config --global core.editor vim + git config --global merge.summary true + +To set up on another computer, you can copy your ``~/.gitconfig`` file, +or run the commands above. + +In detail +========= + +user.name and user.email +------------------------ + +It is good practice to tell git_ who you are, for labeling any changes +you make to the code. The simplest way to do this is from the command +line:: + + git config --global user.name "Your Name" + git config --global user.email you@yourdomain.example.com + +This will write the settings into your git configuration file, which +should now contain a user section with your name and email:: + + [user] + name = Your Name + email = you@yourdomain.example.com + +Of course you'll need to replace ``Your Name`` and ``you@yourdomain.example.com`` +with your actual name and email address. + +Aliases +------- + +You might well benefit from some aliases to common commands. + +For example, you might well want to be able to shorten ``git checkout`` +to ``git co``. Or you may want to alias ``git diff --color-words`` +(which gives a nicely formatted output of the diff) to ``git wdiff`` + +The following ``git config --global`` commands:: + + git config --global alias.ci "commit -a" + git config --global alias.co checkout + git config --global alias.st "status -a" + git config --global alias.stat "status -a" + git config --global alias.br branch + git config --global alias.wdiff "diff --color-words" + +will create an ``alias`` section in your ``.gitconfig`` file with contents +like this:: + + [alias] + ci = commit -a + co = checkout + st = status -a + stat = status -a + br = branch + wdiff = diff --color-words + +Editor +------ + +You may also want to make sure that your editor of choice is used :: + + git config --global core.editor vim + +Merging +------- + +To enforce summaries when doing merges (``~/.gitconfig`` file again):: + + [merge] + log = true + +Or from the command line:: + + git config --global merge.log true + + +.. include:: links.inc diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst new file mode 100644 index 000000000000..be7ab569141a --- /dev/null +++ b/doc/devel/gitwash/development_workflow.rst @@ -0,0 +1,239 @@ +.. _development-workflow: + +==================== +Development workflow +==================== + +You already have your own forked copy of the matplotlib_ repository, by +following :ref:`forking`, :ref:`set-up-fork`, and you have configured +git_ by following :ref:`configure-git`. + +Workflow summary +================ + +* Keep your ``master`` branch clean of edits that have not been merged + to the main matplotlib_ development repo. Your ``master`` then will follow + the main matplotlib_ repository. +* Start a new *feature branch* for each set of edits that you do. +* If you can avoid it, try not to merge other branches into your feature + branch while you are working. +* Ask for review! + +This way of working really helps to keep work well organized, and in +keeping history as clear as possible. + +See |emdash| for example |emdash| `linux git workflow`_. + +Making a new feature branch +=========================== + +:: + + git branch my-new-feature + git checkout my-new-feature + +Generally, you will want to keep this also on your public github_ fork +of matplotlib_. To do this, you `git push`_ this new branch up to your github_ +repo. Generally (if you followed the instructions in these pages, and +by default), git will have a link to your github_ repo, called +``origin``. You push up to your own repo on github_ with:: + + git push origin my-new-feature + +In git >1.7 you can ensure that the link is correctly set by using the +``--set-upstream`` option:: + + git push --set-upstream origin my-new-feature + +From now on git_ will know that ``my-new-feature`` is related to the +``my-new-feature`` branch in the github_ repo. + +The editing workflow +==================== + +Overview +-------- + +:: + + # hack hack + git add my_new_file + git commit -am 'NF - some message' + git push + +In more detail +-------------- + +#. Make some changes +#. See which files have changed with ``git status`` (see `git status`_). + You'll see a listing like this one:: + + # On branch ny-new-feature + # Changed but not updated: + # (use "git add ..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: README + # + # Untracked files: + # (use "git add ..." to include in what will be committed) + # + # INSTALL + no changes added to commit (use "git add" and/or "git commit -a") + +#. Check what the actual changes are with ``git diff`` (`git diff`_). +#. Add any new files to version control ``git add new_file_name`` (see + `git add`_). +#. To commit all modified files into the local copy of your repo,, do + ``git commit -am 'A commit message'``. Note the ``-am`` options to + ``commit``. The ``m`` flag just signals that you're going to type a + message on the command line. The ``a`` flag |emdash| you can just take on + faith |emdash| or see `why the -a flag?`_ |emdash| and the helpful use-case + description in the `tangled working copy problem`_. The `git commit`_ manual + page might also be useful. +#. To push the changes up to your forked repo on github_, do a ``git + push`` (see `git push`). + +Asking for code review +====================== + +#. Go to your repo URL |emdash| e.g. ``http://github.com/your-user-name/matplotlib``. +#. Click on the *Branch list* button: + + .. image:: branch_list.png + +#. Click on the *Compare* button for your feature branch |emdash| here ``my-new-feature``: + + .. image:: branch_list_compare.png + +#. If asked, select the *base* and *comparison* branch names you want to + compare. Usually these will be ``master`` and ``my-new-feature`` + (where that is your feature branch name). +#. At this point you should get a nice summary of the changes. Copy the + URL for this, and post it to the `matplotlib mailing list`_, asking for + review. The URL will look something like: + ``http://github.com/your-user-name/matplotlib/compare/master...my-new-feature``. + There's an example at + http://github.com/matthew-brett/nipy/compare/master...find-install-data + See: http://github.com/blog/612-introducing-github-compare-view for + more detail. + +The generated comparison, is between your feature branch +``my-new-feature``, and the place in ``master`` from which you branched +``my-new-feature``. In other words, you can keep updating ``master`` +without interfering with the output from the comparison. More detail? +Note the three dots in the URL above (``master...my-new-feature``) and +see :ref:`dot2-dot3`. + +Asking for your changes to be merged with the main repo +======================================================= + +When you are ready to ask for the merge of your code: + +#. Go to the URL of your forked repo, say + ``http://github.com/your-user-name/matplotlib.git``. +#. Click on the 'Pull request' button: + + .. image:: pull_button.png + + Enter a message; we suggest you select only ``matplotlib`` as the + recipient. The message will go to the `matplotlib mailing list`_. Please + feel free to add others from the list as you like. + +Merging from trunk +================== + +This updates your code from the upstream `matplotlib github`_ repo. + +Overview +-------- + +:: + + # go to your master branch + git checkout master + # pull changes from github + git fetch upstream + # merge from upstream + git merge upstream/master + +In detail +--------- + +We suggest that you do this only for your ``master`` branch, and leave +your 'feature' branches unmerged, to keep their history as clean as +possible. This makes code review easier:: + + git checkout master + +Make sure you have done :ref:`linking-to-upstream`. + +Merge the upstream code into your current development by first pulling +the upstream repo to a copy on your local machine:: + + git fetch upstream + +then merging into your current branch:: + + git merge upstream/master + +Deleting a branch on github_ +============================ + +:: + + git checkout master + # delete branch locally + git branch -D my-unwanted-branch + # delete branch on github + git push origin :my-unwanted-branch + +(Note the colon ``:`` before ``test-branch``. See also: +http://github.com/guides/remove-a-remote-branch + +Several people sharing a single repository +========================================== + +If you want to work on some stuff with other people, where you are all +committing into the same repository, or even the same branch, then just +share it via github_. + +First fork matplotlib into your account, as from :ref:`forking`. + +Then, go to your forked repository github page, say +``http://github.com/your-user-name/matplotlib`` + +Click on the 'Admin' button, and add anyone else to the repo as a +collaborator: + + .. image:: pull_button.png + +Now all those people can do:: + + git clone git@githhub.com:your-user-name/matplotlib.git + +Remember that links starting with ``git@`` use the ssh protocol and are +read-write; links starting with ``git://`` are read-only. + +Your collaborators can then commit directly into that repo with the +usual:: + + git commit -am 'ENH - much better code' + git push origin master # pushes directly into your repo + +Exploring your repository +========================= + +To see a graphical representation of the repository branches and +commits:: + + gitk --all + +To see a linear list of commits for this branch:: + + git log + +You can also look at the `network graph visualizer`_ for your github_ +repo. + +.. include:: links.inc diff --git a/doc/devel/gitwash/dot2_dot3.rst b/doc/devel/gitwash/dot2_dot3.rst new file mode 100644 index 000000000000..7759e2e60d68 --- /dev/null +++ b/doc/devel/gitwash/dot2_dot3.rst @@ -0,0 +1,28 @@ +.. _dot2-dot3: + +======================================== + Two and three dots in difference specs +======================================== + +Thanks to Yarik Halchenko for this explanation. + +Imagine a series of commits A, B, C, D... Imagine that there are two +branches, *topic* and *master*. You branched *topic* off *master* when +*master* was at commit 'E'. The graph of the commits looks like this:: + + + A---B---C topic + / + D---E---F---G master + +Then:: + + git diff master..topic + +will output the difference from G to C (i.e. with effects of F and G), +while:: + + git diff master...topic + +would output just differences in the topic branch (i.e. only A, B, and +C). diff --git a/doc/devel/gitwash/following_latest.rst b/doc/devel/gitwash/following_latest.rst new file mode 100644 index 000000000000..4419abd82d69 --- /dev/null +++ b/doc/devel/gitwash/following_latest.rst @@ -0,0 +1,36 @@ +.. _following-latest: + +============================= + Following the latest source +============================= + +These are the instructions if you just want to follow the latest +*matplotlib* source, but you don't need to do any development for now. + +The steps are: + +* :ref:`install-git` +* get local copy of the git repository from github_ +* update local copy from time to time + +Get the local copy of the code +============================== + +From the command line:: + + git clone git://github.com/matplotlib/matplotlib.git + +You now have a copy of the code tree in the new ``matplotlib`` directory. + +Updating the code +================= + +From time to time you may want to pull down the latest code. Do this with:: + + cd matplotlib + git pull + +The tree in ``matplotlib`` will now have the latest changes from the initial +repository. + +.. include:: links.inc diff --git a/doc/devel/gitwash/forking_button.png b/doc/devel/gitwash/forking_button.png new file mode 100644 index 000000000000..d0e04134d4d0 Binary files /dev/null and b/doc/devel/gitwash/forking_button.png differ diff --git a/doc/devel/gitwash/forking_hell.rst b/doc/devel/gitwash/forking_hell.rst new file mode 100644 index 000000000000..00e937ffd842 --- /dev/null +++ b/doc/devel/gitwash/forking_hell.rst @@ -0,0 +1,33 @@ +.. _forking: + +========================================== +Making your own copy (fork) of matplotlib +========================================== + +You need to do this only once. The instructions here are very similar +to the instructions at http://help.github.com/forking/ |emdash| please see +that page for more detail. We're repeating some of it here just to give the +specifics for the matplotlib_ project, and to suggest some default names. + +Set up and configure a github_ account +====================================== + +If you don't have a github_ account, go to the github_ page, and make one. + +You then need to configure your account to allow write access |emdash| see +the ``Generating SSH keys`` help on `github help`_. + +Create your own forked copy of matplotlib_ +=========================================== + +#. Log into your github_ account. +#. Go to the matplotlib_ github home at `matplotlib github`_. +#. Click on the *fork* button: + + .. image:: forking_button.png + + Now, after a short pause and some 'Hardcore forking action', you + should find yourself at the home page for your own forked copy of matplotlib_. + +.. include:: links.inc + diff --git a/doc/devel/gitwash/git_development.rst b/doc/devel/gitwash/git_development.rst new file mode 100644 index 000000000000..64522c6581c7 --- /dev/null +++ b/doc/devel/gitwash/git_development.rst @@ -0,0 +1,16 @@ +.. _git-development: + +===================== + Git for development +===================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + forking_hell + set_up_fork + configure_git + development_workflow + diff --git a/doc/devel/gitwash/git_install.rst b/doc/devel/gitwash/git_install.rst new file mode 100644 index 000000000000..a87224d4e412 --- /dev/null +++ b/doc/devel/gitwash/git_install.rst @@ -0,0 +1,26 @@ +.. _install-git: + +============= + Install git +============= + +Overview +======== + +================ ============= +Debian / Ubuntu ``sudo apt-get install git-core`` +Fedora ``sudo yum install git-core`` +Windows Download and install msysGit_ +OS X Use the git-osx-installer_ +================ ============= + +In detail +========= + +See the git_ page for the most recent information. + +Have a look at the github_ install help pages available from `github help`_ + +There are good instructions here: http://book.git-scm.com/2_installing_git.html + +.. include:: links.inc diff --git a/doc/devel/gitwash/git_intro.rst b/doc/devel/gitwash/git_intro.rst new file mode 100644 index 000000000000..786eb84d5bd3 --- /dev/null +++ b/doc/devel/gitwash/git_intro.rst @@ -0,0 +1,18 @@ +============== + Introduction +============== + +These pages describe a git_ and github_ workflow for the matplotlib_ +project. + +There are several different workflows here, for different ways of +working with *matplotlib*. + +This is not a comprehensive git_ reference, it's just a workflow for our +own project. It's tailored to the github_ hosting service. You may well +find better or quicker ways of getting stuff done with git_, but these +should get you started. + +For general resources for learning git_ see :ref:`git-resources`. + +.. include:: links.inc diff --git a/doc/devel/gitwash/git_links.inc b/doc/devel/gitwash/git_links.inc new file mode 100644 index 000000000000..14a76f5056fb --- /dev/null +++ b/doc/devel/gitwash/git_links.inc @@ -0,0 +1,54 @@ +.. This (-*- rst -*-) format file contains commonly used link targets + and name substitutions. It may be included in many files, + therefore it should only contain link targets and name + substitutions. Try grepping for "^\.\. _" to find plausible + candidates for this list. + +.. NOTE: reST targets are + __not_case_sensitive__, so only one target definition is needed for + nipy, NIPY, Nipy, etc... + +.. git stuff +.. _git: http://git-scm.com/ +.. _github: http://github.com +.. _github help: http://help.github.com +.. _msysgit: http://code.google.com/p/msysgit/downloads/list +.. _git-osx-installer: http://code.google.com/p/git-osx-installer/downloads/list +.. _subversion: http://subversion.tigris.org/ +.. _git cheat sheet: http://github.com/guides/git-cheat-sheet +.. _pro git book: http://progit.org/ +.. _git svn crash course: http://git-scm.com/course/svn.html +.. _learn.github: http://learn.github.com/ +.. _network graph visualizer: http://github.com/blog/39-say-hello-to-the-network-graph-visualizer +.. _git user manual: http://www.kernel.org/pub/software/scm/git/docs/user-manual.html +.. _git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html +.. _git community book: http://book.git-scm.com/ +.. _git ready: http://www.gitready.com/ +.. _git casts: http://www.gitcasts.com/ +.. _Fernando's git page: http://www.fperez.org/py4science/git.html +.. _git magic: http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html +.. _git concepts: http://www.eecs.harvard.edu/~cduan/technical/git/ +.. _git clone: http://www.kernel.org/pub/software/scm/git/docs/git-clone.html +.. _git checkout: http://www.kernel.org/pub/software/scm/git/docs/git-checkout.html +.. _git commit: http://www.kernel.org/pub/software/scm/git/docs/git-commit.html +.. _git push: http://www.kernel.org/pub/software/scm/git/docs/git-push.html +.. _git pull: http://www.kernel.org/pub/software/scm/git/docs/git-pull.html +.. _git add: http://www.kernel.org/pub/software/scm/git/docs/git-add.html +.. _git status: http://www.kernel.org/pub/software/scm/git/docs/git-status.html +.. _git diff: http://www.kernel.org/pub/software/scm/git/docs/git-diff.html +.. _git log: http://www.kernel.org/pub/software/scm/git/docs/git-log.html +.. _git branch: http://www.kernel.org/pub/software/scm/git/docs/git-branch.html +.. _git remote: http://www.kernel.org/pub/software/scm/git/docs/git-remote.html +.. _git config: http://www.kernel.org/pub/software/scm/git/docs/git-config.html +.. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html +.. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html +.. _tangled working copy problem: http://tomayko.com/writings/the-thing-about-git +.. _git management: http://kerneltrap.org/Linux/Git_Management +.. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html +.. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html +.. _git foundation: http://matthew-brett.github.com/pydagogue/foundation.html + +.. other stuff +.. _python: http://www.python.org + +.. |emdash| unicode:: U+02014 diff --git a/doc/devel/gitwash/git_resources.rst b/doc/devel/gitwash/git_resources.rst new file mode 100644 index 000000000000..0fb030f77299 --- /dev/null +++ b/doc/devel/gitwash/git_resources.rst @@ -0,0 +1,59 @@ +.. _git-resources: + +================ + git_ resources +================ + +Tutorials and summaries +======================= + +* `github help`_ has an excellent series of how-to guides. +* `learn.github`_ has an excellent series of tutorials +* The `pro git book`_ is a good in-depth book on git. +* A `git cheat sheet`_ is a page giving summaries of common commands. +* The `git user manual`_ +* The `git tutorial`_ +* The `git community book`_ +* `git ready`_ |emdash| a nice series of tutorials +* `git casts`_ |emdash| video snippets giving git how-tos. +* `git magic`_ |emdash| extended introduction with intermediate detail +* The `git parable`_ is an easy read explaining the concepts behind git. +* Our own `git foundation`_ expands on the `git parable`_. +* Fernando Perez' git page |emdash| `Fernando's git page`_ |emdash| many + links and tips +* A good but technical page on `git concepts`_ +* `git svn crash course`_: git_ for those of us used to subversion_ + +Advanced git workflow +===================== + +There are many ways of working with git_; here are some posts on the +rules of thumb that other projects have come up with: + +* Linus Torvalds on `git management`_ +* Linus Torvalds on `linux git workflow`_ . Summary; use the git tools + to make the history of your edits as clean as possible; merge from + upstream edits as little as possible in branches where you are doing + active development. + +Manual pages online +=================== + +You can get these on your own machine with (e.g) ``git help push`` or +(same thing) ``git push --help``, but, for convenience, here are the +online manual pages for some common commands: + +* `git add`_ +* `git branch`_ +* `git checkout`_ +* `git clone`_ +* `git commit`_ +* `git config`_ +* `git diff`_ +* `git log`_ +* `git pull`_ +* `git push`_ +* `git remote`_ +* `git status`_ + +.. include:: links.inc diff --git a/doc/devel/gitwash/index.rst b/doc/devel/gitwash/index.rst new file mode 100644 index 000000000000..e94b66ead41e --- /dev/null +++ b/doc/devel/gitwash/index.rst @@ -0,0 +1,18 @@ +.. _using-git: + +Working with *matplotlib* source code +====================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + git_intro + git_install + following_latest + patching + git_development + git_resources + + diff --git a/doc/devel/gitwash/known_projects.inc b/doc/devel/gitwash/known_projects.inc new file mode 100644 index 000000000000..297235287796 --- /dev/null +++ b/doc/devel/gitwash/known_projects.inc @@ -0,0 +1,41 @@ +.. Known projects + +.. PROJECTNAME placeholders +.. _PROJECTNAME: http://neuroimaging.scipy.org +.. _`PROJECTNAME github`: http://github.com/nipy +.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel + +.. numpy +.. _numpy: hhttp://numpy.scipy.org +.. _`numpy github`: http://github.com/numpy/numpy +.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion + +.. scipy +.. _scipy: http://www.scipy.org +.. _`scipy github`: http://github.com/scipy/scipy +.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev + +.. nipy +.. _nipy: http://nipy.org/nipy +.. _`nipy github`: http://github.com/nipy/nipy +.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel + +.. ipython +.. _ipython: http://ipython.scipy.org +.. _`ipython github`: http://github.com/ipython/ipython +.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev + +.. dipy +.. _dipy: http://nipy.org/dipy +.. _`dipy github`: http://github.com/Garyfallidis/dipy +.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel + +.. nibabel +.. _nibabel: http://nipy.org/nibabel +.. _`nibabel github`: http://github.com/nipy/nibabel +.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel + +.. marsbar +.. _marsbar: http://marsbar.sourceforge.net +.. _`marsbar github`: http://github.com/matthew-brett/marsbar +.. _`MarsBaR mailing list`: https://lists.sourceforge.net/lists/listinfo/marsbar-users diff --git a/doc/devel/gitwash/links.inc b/doc/devel/gitwash/links.inc new file mode 100644 index 000000000000..20f4dcfffd4a --- /dev/null +++ b/doc/devel/gitwash/links.inc @@ -0,0 +1,4 @@ +.. compiling links file +.. include:: known_projects.inc +.. include:: this_project.inc +.. include:: git_links.inc diff --git a/doc/devel/gitwash/patching.rst b/doc/devel/gitwash/patching.rst new file mode 100644 index 000000000000..6f7733125c88 --- /dev/null +++ b/doc/devel/gitwash/patching.rst @@ -0,0 +1,134 @@ +================ + Making a patch +================ + +You've discovered a bug or something else you want to change +in matplotlib_ .. |emdash| excellent! + +You've worked out a way to fix it |emdash| even better! + +You want to tell us about it |emdash| best of all! + +The easiest way is to make a *patch* or set of patches. Here +we explain how. Making a patch is the simplest and quickest, +but if you're going to be doing anything more than simple +quick things, please consider following the +:ref:`git-development` model instead. + +.. _making-patches: + +Making patches +============== + +Overview +-------- + +:: + + # tell git who you are + git config --global user.email you@yourdomain.example.com + git config --global user.name "Your Name Comes Here" + # get the repository if you don't have it + git clone git://github.com/matplotlib/matplotlib.git + # make a branch for your patching + cd matplotlib + git branch the-fix-im-thinking-of + git checkout the-fix-im-thinking-of + # hack, hack, hack + # Tell git about any new files you've made + git add somewhere/tests/test_my_bug.py + # commit work in progress as you go + git commit -am 'BF - added tests for Funny bug' + # hack hack, hack + git commit -am 'BF - added fix for Funny bug' + # make the patch files + git format-patch -M -C master + +Then, send the generated patch files to the `matplotlib +mailing list`_ |emdash| where we will thank you warmly. + +In detail +--------- + +#. Tell git_ who you are so it can label the commits you've + made:: + + git config --global user.email you@yourdomain.example.com + git config --global user.name "Your Name Comes Here" + +#. If you don't already have one, clone a copy of the + matplotlib_ repository:: + + git clone git://github.com/matplotlib/matplotlib.git + cd matplotlib + +#. Make a 'feature branch'. This will be where you work on + your bug fix. It's nice and safe and leaves you with + access to an unmodified copy of the code in the main + branch:: + + git branch the-fix-im-thinking-of + git checkout the-fix-im-thinking-of + +#. Do some edits, and commit them as you go:: + + # hack, hack, hack + # Tell git about any new files you've made + git add somewhere/tests/test_my_bug.py + # commit work in progress as you go + git commit -am 'BF - added tests for Funny bug' + # hack hack, hack + git commit -am 'BF - added fix for Funny bug' + + Note the ``-am`` options to ``commit``. The ``m`` flag just + signals that you're going to type a message on the command + line. The ``a`` flag |emdash| you can just take on faith |emdash| + or see `why the -a flag?`_. + +#. When you have finished, check you have committed all your + changes:: + + git status + +#. Finally, make your commits into patches. You want all the + commits since you branched from the ``master`` branch:: + + git format-patch -M -C master + + You will now have several files named for the commits:: + + 0001-BF-added-tests-for-Funny-bug.patch + 0002-BF-added-fix-for-Funny-bug.patch + + Send these files to the `matplotlib mailing list`_. + +When you are done, to switch back to the main copy of the +code, just return to the ``master`` branch:: + + git checkout master + +Moving from patching to development +=================================== + +If you find you have done some patches, and you have one or +more feature branches, you will probably want to switch to +development mode. You can do this with the repository you +have. + +Fork the matplotlib_ repository on github_ |emdash| :ref:`forking`. +Then:: + + # checkout and refresh master branch from main repo + git checkout master + git pull origin master + # rename pointer to main repository to 'upstream' + git remote rename origin upstream + # point your repo to default read / write to your fork on github + git remote add origin git@github.com:your-user-name/matplotlib.git + # push up any branches you've made and want to keep + git push origin the-fix-im-thinking-of + +Then you can, if you want, follow the +:ref:`development-workflow`. + +.. include:: links.inc diff --git a/doc/devel/gitwash/pull_button.png b/doc/devel/gitwash/pull_button.png new file mode 100644 index 000000000000..e5031681b97b Binary files /dev/null and b/doc/devel/gitwash/pull_button.png differ diff --git a/doc/devel/gitwash/set_up_fork.rst b/doc/devel/gitwash/set_up_fork.rst new file mode 100644 index 000000000000..a9d8faa153f2 --- /dev/null +++ b/doc/devel/gitwash/set_up_fork.rst @@ -0,0 +1,68 @@ +.. _set-up-fork: + +================== + Set up your fork +================== + +First you follow the instructions for :ref:`forking`. + +Overview +======== + +:: + + git clone git@github.com:your-user-name/matplotlib.git + cd matplotlib + git remote add upstream git://github.com/matplotlib/matplotlib.git + +In detail +========= + +Clone your fork +--------------- + +#. Clone your fork to the local computer with ``git clone + git@github.com:your-user-name/matplotlib.git`` +#. Investigate. Change directory to your new repo: ``cd matplotlib``. Then + ``git branch -a`` to show you all branches. You'll get something + like:: + + * master + remotes/origin/master + + This tells you that you are currently on the ``master`` branch, and + that you also have a ``remote`` connection to ``origin/master``. + What remote repository is ``remote/origin``? Try ``git remote -v`` to + see the URLs for the remote. They will point to your github_ fork. + + Now you want to connect to the upstream `matplotlib github`_ repository, so + you can merge in changes from trunk. + +.. _linking-to-upstream: + +Linking your repository to the upstream repo +-------------------------------------------- + +:: + + cd matplotlib + git remote add upstream git://github.com/matplotlib/matplotlib.git + +``upstream`` here is just the arbitrary name we're using to refer to the +main matplotlib_ repository at `matplotlib github`_. + +Note that we've used ``git://`` for the URL rather than ``git@``. The +``git://`` URL is read only. This means we that we can't accidentally +(or deliberately) write to the upstream repo, and we are only going to +use it to merge into our own code. + +Just for your own satisfaction, show yourself that you now have a new +'remote', with ``git remote -v show``, giving you something like:: + + upstream git://github.com/matplotlib/matplotlib.git (fetch) + upstream git://github.com/matplotlib/matplotlib.git (push) + origin git@github.com:your-user-name/matplotlib.git (fetch) + origin git@github.com:your-user-name/matplotlib.git (push) + +.. include:: links.inc + diff --git a/doc/devel/gitwash/this_project.inc b/doc/devel/gitwash/this_project.inc new file mode 100644 index 000000000000..8ce111ce07a6 --- /dev/null +++ b/doc/devel/gitwash/this_project.inc @@ -0,0 +1,5 @@ +.. matplotlib +.. _matplotlib: http://matplotlib.sourceforge.net +.. _`matplotlib github`: http://github.com/matplotlib/matplotlib + +.. _`matplotlib mailing list`: https://lists.sourceforge.net/lists/listinfo/matplotlib-devel diff --git a/doc/devel/release_guide.rst b/doc/devel/release_guide.rst index 167fd541422e..e79a2a90b937 100644 --- a/doc/devel/release_guide.rst +++ b/doc/devel/release_guide.rst @@ -36,13 +36,9 @@ Testing Branching ============ -Once all the tests are passing and you are ready to do a release, you -need to create a release branch and configure svn-merge to use it; -Michael Droettboom should probably handle this step, but if he is not -available see instructions at :ref:`setting-up-svnmerge`. On the -bracnh, do any additional testing you want to do, and then build -binaries and source distributions for testing as release candidates. - +Once all the tests are passing and you are ready to do a release, you need to +create a release branch, do any additional testing you want to do, and then +build binaries and source distributions for testing as release candidates. .. _release-packaging: @@ -53,10 +49,6 @@ Packaging * Make sure the :file:`MANIFEST.in` us up to date and remove :file:`MANIFEST` so it will be rebuilt by MANIFEST.in -* run `svn-clean - `_ - from in the mpl svn directory before building the sdist - * unpack the sdist and make sure you can build from that directory * Use :file:`setup.cfg` to set the default backends. For windows and @@ -91,10 +83,9 @@ you can do:: replacing 'jdh2358' with your sourceforge login. -Any changes to fix bugs in the release candidate should be fixed in -the release branch and merged into the trunk with svn-merge; see -:ref:`svn-merge`. When the release candidate is signed off on, build -the final sdist, binaries and eggs, and upload them to the sourceforge +Any changes to fix bugs in the release candidate should be fixed in the release +branch and merged into the trunk. When the release candidate is signed off on, +build the final sdist, binaries and eggs, and upload them to the sourceforge release area. @@ -110,7 +101,6 @@ Uploading * ftp the source and binaries to the anonymous FTP site:: - mpl> svn-clean mpl> python setup.py sdist mpl> cd dist/ dist> sftp jdh2358@frs.sourceforge.net diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst index 90973db4ea52..f64105ab5b04 100644 --- a/doc/faq/howto_faq.rst +++ b/doc/faq/howto_faq.rst @@ -525,15 +525,8 @@ Contributing: howto Submit a patch ----------------- -First obtain a copy of matplotlib svn (see :ref:`install-svn`) and -make your changes to the matplotlib source code or documentation and -apply a `svn diff`. If it is feasible, do your diff from the top -level directory, the one that contains :file:`setup.py`. Eg,:: - - > cd /path/to/matplotlib/source - > svn diff > mypatch.diff - -and then post your patch to the `matplotlib-devel +See :ref:`making-patches` if you have any questions about how +to create a patch. Once you've created a patch, post it to the `matplotlib-devel `_ mailing list. If you do not get a response within 24 hours, post your patch to the sourceforge patch `tracker @@ -545,14 +538,14 @@ list. If you have made lots of local changes and do not want to a diff against the entire tree, but rather against a single directory or -file, that is fine, but we do prefer svn diffs against the top level +file, that is fine, but we do prefer diffs against the top level (where setup.py lives) since it is nice to have a consistent way to apply them. If you are posting a patch to fix a code bug, please explain your patch in words -- what was broken before and how you fixed it. Also, even if your patch is particularly simple, just a few lines or a -single function replacement, we encourage people to submit svn diffs +single function replacement, we encourage people to submit diffs against HEAD or the branch they are patching. It just makes life simpler for us, since we (fortunately) get a lot of contributions, and want to receive them in a standard format. If possible, for any @@ -619,7 +612,7 @@ your documents. Once your documentation contributions are working (and hopefully tested by actually *building* the docs) you can submit them as a patch -against svn. See :ref:`install-svn` and :ref:`how-to-submit-patch`. +against git. See :ref:`install-git` and :ref:`how-to-submit-patch`. Looking for something to do? Search for `TODO <../search.html?q=todo>`_. diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst index 883fdf3329b3..60e18be560d1 100644 --- a/doc/faq/installing_faq.rst +++ b/doc/faq/installing_faq.rst @@ -92,14 +92,14 @@ install directory. To cleanly rebuild: ` -.. _install-svn: +.. _install-git: -Install from svn +Install from git ================ Checking out the main source:: - svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/matplotlib matplotlib + git clone git://github.com/matthew-brett/gitwash.git and build and install as usual with:: @@ -114,7 +114,7 @@ and build and install as usual with:: sudo apt-get build_dep python-matplotlib This does not build matplotlib, but it does get the install the - build dependencies, which will make building from svn easy. + build dependencies, which will make building from git easy. If you want to be able to follow the development branch as it changes just replace @@ -125,20 +125,16 @@ the last step with (Make sure you have **setuptools** installed):: This creates links in the right places and installs the command line script to the appropriate places. Then, if you want to update your **matplotlib** at any time, just do:: - > svn update - + > git pull -When you run `svn update`, if the output shows that only Python files +When you run `git pull`, if the output shows that only Python files have been updated, you are all set. If C files have changed, you need to run the `python setupegg develop` command again to compile them. -There is more information on :ref:`using Subversion ` in -the developer docs. - -Install from git -================ +There is more information on using git in the +:ref:`development quickstart ` +documentation. -See :ref:`using-git`. Backends ======== @@ -436,7 +432,7 @@ Run this script (for example ``sh ./install-matplotlib-epd-osx.sh``) in the directory in which you want the source code to be placed, or simply type the commands in the terminal command line. This script sets some local variable (CFLAGS, LDFLAGS, PKG_CONFIG_PATH, ARCHFLAGS), removes previous installations, -checks out the source from svn, builds and installs it. The backend seems to be +checks out the source from git, builds and installs it. The backend seems to be set to MacOSX. diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst index 7156c6dfebde..dda13cd01b9a 100644 --- a/doc/faq/troubleshooting_faq.rst +++ b/doc/faq/troubleshooting_faq.rst @@ -127,25 +127,25 @@ a bug and can not be quickly solved, you may be asked to file a bug in the tracker so the issue doesn't get lost. -.. _svn-trouble: +.. _git-trouble: -Problems with recent svn versions +Problems with recent got versions =============================================================== First make sure you have a clean build and install (see -:ref:`clean-install`), get the latest svn update, install it and run a +:ref:`clean-install`), get the latest git update, install it and run a simple test script in debug mode:: rm -rf build rm -rf /path/to/site-packages/matplotlib* - svn up + git pull python setup.py install > build.out python examples/pylab_examples/simple_plot.py --verbose-debug > run.out and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel `_ -mailing list (please do not post svn problems to the `users list +mailing list (please do not post git problems to the `users list `_). Of course, you will want to clearly describe your problem, what you diff --git a/doc/users/credits.rst b/doc/users/credits.rst index 8c9e1be4e33a..a70f9c8c1452 100644 --- a/doc/users/credits.rst +++ b/doc/users/credits.rst @@ -126,7 +126,7 @@ Sigve Tjoraand, Ted Drain, James Evans features including custom unit types, datetime support, scale free ellipses, broken bar plots and more. The JPL team wrote the unit testing image comparison `infrastructure - `_ + `_ for regression test image comparisons. James Amundson @@ -140,7 +140,7 @@ Eric Firing Daishi Harada added support for "Dashed Text". See `dashpointlabel.py - `_ and + `_ and :class:`~matplotlib.text.TextWithDash`. Nicolas Young diff --git a/doc/users/installing.rst b/doc/users/installing.rst index 4faea15844fa..48a17b11dbd2 100644 --- a/doc/users/installing.rst +++ b/doc/users/installing.rst @@ -98,7 +98,7 @@ build everything yourself, it is not difficult to build matplotlib from source. Grab the latest *tar.gz* release file from `sourceforge `_, or if you want to develop matplotlib or just need the latest bugfixed -version, grab the latest svn version :ref:`install-svn`. +version, grab the latest git version :ref:`install-git`. Once you have satisfied the requirements detailed below (mainly python, numpy, libpng and freetype), you build matplotlib in the usual @@ -109,7 +109,7 @@ way:: python setup.py install We provide a `setup.cfg -`_ +`_ file that lives along :file:`setup.py` which you can use to customize the build process, for example, which default backend to use, whether some of the optional libraries that matplotlib ships with are @@ -139,7 +139,7 @@ libraries themselves. sudo apt-get build_dep python-matplotlib This does not build matplotlib, but it does get the install the - build dependencies, which will make building from svn easy. + build dependencies, which will make building from git easy. :term:`python` 2.4 (or later but not python3) @@ -221,7 +221,7 @@ The build situation on OSX is complicated by the various places one can get the png and freetype requirements from (darwinports, fink, /usr/X11R6) and the different architectures (x86, ppc, universal) and the different OSX version (10.4 and 10.5). We recommend that you build -the way we do for the OSX release: by grabbing the tarbar or svn +the way we do for the OSX release: by grabbing the tarbar or git repository, cd-ing into the release/osx dir, and following the instruction in the README. This directory has a Makefile which will automatically grab the zlib, png and freetype dependencies from the diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst index d2197942e292..e49dbea9c10e 100644 --- a/doc/users/whats_new.rst +++ b/doc/users/whats_new.rst @@ -120,7 +120,7 @@ been, thanks to improved `software carpentry `_. We now have a `buildbot `_ which runs a suite of `nose `_ regression tests on every -svn commit, auto-generating a set of images and comparing them against +git commit, auto-generating a set of images and comparing them against a set of known-goods, sending emails to developers on failures with a pixel-by-pixel `image comparison `_. Releases and release diff --git a/examples/misc/developer_commit_history.py b/examples/misc/developer_commit_history.py index 759fea87a804..49cc5f6c1368 100644 --- a/examples/misc/developer_commit_history.py +++ b/examples/misc/developer_commit_history.py @@ -2,7 +2,7 @@ report how many days it has been since each developer committed. You must do an -svn log > log.txt +git log > log.txt and place the output next to this file before running @@ -14,7 +14,7 @@ todate = cbook.todate('%Y-%m-%d') today = datetime.date.today() if not os.path.exists('log.txt'): - print('You must place the "svn log" output into a file "log.txt"') + print('You must place the "git log" output into a file "log.txt"') raise SystemExit parse = False diff --git a/examples/misc/sample_data_demo.py b/examples/misc/sample_data_demo.py index eb34a92ceb4e..9f50f9fd0504 100644 --- a/examples/misc/sample_data_demo.py +++ b/examples/misc/sample_data_demo.py @@ -1,6 +1,6 @@ """ Grab mpl data from the ~/.matplotlib/sample_data cache if it exists, else -fetch it from svn and cache it +fetch it from git and cache it """ import matplotlib.cbook as cbook import matplotlib.pyplot as plt diff --git a/examples/misc/sample_data_test.py b/examples/misc/sample_data_test.py index e59eaf0704e8..831e5643a403 100644 --- a/examples/misc/sample_data_test.py +++ b/examples/misc/sample_data_test.py @@ -1,11 +1,11 @@ """ -Demonstrate how get_sample_data works with svn revisions in the data. +Demonstrate how get_sample_data works with git revisions in the data. - svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/sample_data + git clone https://github.com/matplotlib/sample_data.git and edit testdata.csv to add a new row. After committing the changes, when you rerun this script you will get the updated data (and the new -svn version will be cached in ~/.matplotlib/sample_data) +git version will be cached in ~/.matplotlib/sample_data) """ import matplotlib.mlab as mlab