DOC: regenerate gitwash docs

17 files changed, 871 insertions, 0 deletions

diff --git a/doc/source/dev/gitwash/branch_list.png b/doc/source/dev/gitwash/branch_list.png
new file mode 100644
index 000000000..1196eb754
--- /dev/null
+++ b/doc/source/dev/gitwash/branch_list.png
diff --git a/doc/source/dev/gitwash/branch_list_compare.png b/doc/source/dev/gitwash/branch_list_compare.png
new file mode 100644
index 000000000..336afa374
--- /dev/null
+++ b/doc/source/dev/gitwash/branch_list_compare.png
diff --git a/doc/source/dev/gitwash/configure_git.rst b/doc/source/dev/gitwash/configure_git.rst
new file mode 100644
index 000000000..fd6d69d55
--- /dev/null
+++ b/doc/source/dev/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:: git_links.inc
diff --git a/doc/source/dev/gitwash/development_workflow.rst b/doc/source/dev/gitwash/development_workflow.rst
new file mode 100644
index 000000000..2d9248054
--- /dev/null
+++ b/doc/source/dev/gitwash/development_workflow.rst
@@ -0,0 +1,239 @@
+.. _development-workflow:
+
+====================
+Development workflow
+====================
+
+You already have your own forked copy of the NumPy_ 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 NumPy_ development repo.  Your ``master`` then will follow
+  the main NumPy_ 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 - for example - `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 NumPy_.  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 <file>..." to update what will be committed)
+     #   (use "git checkout -- <file>..." to discard changes in working directory)
+     #
+     #	modified:   README
+     #
+     # Untracked files:
+     #   (use "git add <file>..." 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 - you can just take on
+   faith - or see `why the -a flag?`_ - 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 - e.g. ``http://github.com/your-user-name/numpy``.
+#. Click on the *Branch list* button:
+
+   .. image:: branch_list.png
+
+#. Click on the *Compare* button for your feature branch - 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 `NumPy mailing list`_, asking for
+   review.  The URL will look something like:
+   ``http://github.com/your-user-name/numpy/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/numpy.git``.
+#. Click on the 'Pull request' button:
+
+   .. image:: pull_button.png
+
+   Enter a message; we suggest you select only ``NumPy`` as the
+   recipient.  The message will go to the `NumPy mailing list`_.  Please
+   feel free to add others from the list as you like.
+
+Merging from trunk
+==================
+
+This updates your code from the upstream `NumPy 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 NumPy into your account, as from :ref:`forking`.
+
+Then, go to your forked repository github page, say
+``http://github.com/your-user-name/numpy``
+
+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/numpy.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:: git_links.inc
diff --git a/doc/source/dev/gitwash/dot2_dot3.rst b/doc/source/dev/gitwash/dot2_dot3.rst
new file mode 100644
index 000000000..7759e2e60
--- /dev/null
+++ b/doc/source/dev/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/source/dev/gitwash/following_latest.rst b/doc/source/dev/gitwash/following_latest.rst
new file mode 100644
index 000000000..c74cb88bf
--- /dev/null
+++ b/doc/source/dev/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
+*NumPy* 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/numpy/numpy.git
+
+You now have a copy of the code tree in the new ``numpy`` directory.
+
+Updating the code
+=================
+
+From time to time you may want to pull down the latest code.  Do this with::
+
+   cd numpy
+   git pull
+
+The tree in ``numpy`` will now have the latest changes from the initial
+repository.
+
+.. include:: git_links.inc
diff --git a/doc/source/dev/gitwash/forking_button.png b/doc/source/dev/gitwash/forking_button.png
new file mode 100644
index 000000000..d0e04134d
--- /dev/null
+++ b/doc/source/dev/gitwash/forking_button.png
diff --git a/doc/source/dev/gitwash/forking_hell.rst b/doc/source/dev/gitwash/forking_hell.rst
new file mode 100644
index 000000000..3af444e0b
--- /dev/null
+++ b/doc/source/dev/gitwash/forking_hell.rst
@@ -0,0 +1,33 @@
+.. _forking:
+
+==========================================
+Making your own copy (fork) of NumPy
+==========================================
+
+You need to do this only once.  The instructions here are very similar
+to the instructions at http://help.github.com/forking/ - please see that
+page for more detail.  We're repeating some of it here just to give the
+specifics for the NumPy_ 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 - see the
+``Generating SSH keys`` help on `github help`_.
+
+Create your own forked copy of NumPy_
+=========================================
+
+#. Log into your github_ account.
+#. Go to the NumPy_ github home at `NumPy 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 NumPy_.
+
+.. include:: git_links.inc
+
diff --git a/doc/source/dev/gitwash/git_development.rst b/doc/source/dev/gitwash/git_development.rst
new file mode 100644
index 000000000..64522c658
--- /dev/null
+++ b/doc/source/dev/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/source/dev/gitwash/git_install.rst b/doc/source/dev/gitwash/git_install.rst
new file mode 100644
index 000000000..422bdf66a
--- /dev/null
+++ b/doc/source/dev/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:: git_links.inc
diff --git a/doc/source/dev/gitwash/git_intro.rst b/doc/source/dev/gitwash/git_intro.rst
new file mode 100644
index 000000000..655804383
--- /dev/null
+++ b/doc/source/dev/gitwash/git_intro.rst
@@ -0,0 +1,18 @@
+==============
+ Introduction
+==============
+
+These pages describe a git_ and github_ workflow for the NumPy_
+project.
+
+There are several different workflows here, for different ways of
+working with *NumPy*.
+
+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:: git_links.inc
diff --git a/doc/source/dev/gitwash/git_links.inc b/doc/source/dev/gitwash/git_links.inc
new file mode 100644
index 000000000..e33dacc2a
--- /dev/null
+++ b/doc/source/dev/gitwash/git_links.inc
@@ -0,0 +1,85 @@
+.. 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...
+
+.. PROJECTNAME placeholders
+.. _PROJECTNAME: http://neuroimaging.scipy.org
+.. _`PROJECTNAME github`: http://github.com/nipy
+.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
+
+.. 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
+
+.. 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
+.. _NumPy: http://numpy.scipy.org
+.. _`NumPy github`: http://github.com/numpy/numpy
+.. _`NumPy mailing list`: http://scipy.org/Mailing_Lists
diff --git a/doc/source/dev/gitwash/git_resources.rst b/doc/source/dev/gitwash/git_resources.rst
new file mode 100644
index 000000000..ae350806e
--- /dev/null
+++ b/doc/source/dev/gitwash/git_resources.rst
@@ -0,0 +1,58 @@
+.. _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`_ - a nice series of tutorials
+* `git casts`_ - video snippets giving git how-tos.
+* `git magic`_ - 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 - `Fernando's git page`_ - 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:: git_links.inc
diff --git a/doc/source/dev/gitwash/index.rst b/doc/source/dev/gitwash/index.rst
new file mode 100644
index 000000000..aecef1464
--- /dev/null
+++ b/doc/source/dev/gitwash/index.rst
@@ -0,0 +1,18 @@
+.. _using-git:
+
+Working with *NumPy* source code
+======================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   git_intro
+   git_install
+   following_latest
+   patching
+   git_development
+   git_resources
+
+
diff --git a/doc/source/dev/gitwash/patching.rst b/doc/source/dev/gitwash/patching.rst
new file mode 100644
index 000000000..01ece8fc6
--- /dev/null
+++ b/doc/source/dev/gitwash/patching.rst
@@ -0,0 +1,123 @@
+================
+ Making a patch
+================
+
+You've discovered a bug or something else you want to change in NumPy_ - excellent!
+
+You've worked out a way to fix it - even better!
+
+You want to tell us about it - 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/numpy/numpy.git
+   # make a branch for your patching
+   cd numpy
+   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 `NumPy mailing list`_ - 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 NumPy_ repository::
+
+      git clone git://github.com/numpy/numpy.git
+      cd numpy
+
+#. 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 - you can just take on faith - 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 `NumPy 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 NumPy_ repository on github_ - :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/numpy.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:: git_links.inc
diff --git a/doc/source/dev/gitwash/pull_button.png b/doc/source/dev/gitwash/pull_button.png
new file mode 100644
index 000000000..e5031681b
--- /dev/null
+++ b/doc/source/dev/gitwash/pull_button.png
diff --git a/doc/source/dev/gitwash/set_up_fork.rst b/doc/source/dev/gitwash/set_up_fork.rst
new file mode 100644
index 000000000..8b964e52a
--- /dev/null
+++ b/doc/source/dev/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/numpy.git
+   cd numpy
+   git remote add upstream git://github.com/numpy/numpy.git
+
+In detail
+=========
+
+Clone your fork
+---------------
+
+#. Clone your fork to the local computer with ``git clone
+   git@github.com:your-user-name/numpy.git``
+#. Investigate.  Change directory to your new repo: ``cd numpy``. 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 `NumPy github`_ repository, so
+   you can merge in changes from trunk.
+
+.. _linking-to-upstream:
+
+Linking your repository to the upstream repo
+--------------------------------------------
+
+::
+
+   cd numpy
+   git remote add upstream git://github.com/numpy/numpy.git
+
+``upstream`` here is just the arbitrary name we're using to refer to the
+main NumPy_ repository at `NumPy 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/numpy/numpy.git (fetch)
+   upstream	git://github.com/numpy/numpy.git (push)
+   origin	git@github.com:your-user-name/numpy.git (fetch)
+   origin	git@github.com:your-user-name/numpy.git (push)
+
+.. include:: git_links.inc
+