Add Git workflow docs from Gitwash.

These are auto-generated docs from the gitwash template.  To improve
anything in the gitwash/ directory, please go instead to that project
and make your improvements upstream:

http://github.com/matthew-brett/gitwash

docs/source/development/gitwash/configure_git.txt

@@ -0,0 +1,89
+.. _configure-git:
+
+===============
+ Configure git
+===============
+
+.. _git-config-basic:
+
+Overview
+========
+
+::
+
+  git config --global user.email [e-mail]
+  git config --global user.name "Your Name Comes Here"
+
+
+In detail
+=========
+
+This is 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.email [e-mail]
+  git config --global user.name "Your Name Comes Here"
+
+This will write the settings into your git configuration file - a file
+called ``.gitconfig`` in your home directory. 
+
+Advanced git configuration
+==========================
+
+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``. 
+
+The easiest way to do this, is to create a ``.gitconfig`` file in your
+home directory, with contents like this::
+
+  [core]
+          editor = emacs
+  [user]
+          email = [e-mail]
+          name = Your Name Comes Here
+  [alias]
+          st = status
+          stat = status
+          co = checkout
+  [color]
+          diff = auto
+          status = true
+
+(of course you'll need to set your email and name, and may want to set
+your editor).  If you prefer, you can do the same thing from the command
+line::
+
+  git config --global core.editor emacs
+  git config --global user.email [e-mail]
+  git config --global user.name "Your Name Comes Here"
+  git config --global alias.st status
+  git config --global alias.stat status
+  git config --global alias.co checkout
+  git config --global color.diff auto
+  git config --global color.status true
+
+These commands will write to your user's git configuration file
+``~/.gitconfig``.
+
+To set up on another computer, you can copy your ``~/.gitconfig`` file,
+or run the commands above.
+
+Other configuration recommended by Yarik
+========================================
+
+In your ``~/.gitconfig`` file alias section::
+
+   wdiff = diff --color-words
+
+so that ``git wdiff`` gives a nicely formatted output of the diff. 
+
+To enforce summaries when doing merges(``~/.gitconfig`` file again)::
+
+   [merge]
+      summary = true
+
+
+.. include:: git_links.txt
+
+

docs/source/development/gitwash/development_workflow.txt

@@ -0,0 +1,233
+.. _development-workflow:
+
+====================
+Development workflow
+====================
+
+You already have your own forked copy of the ipython_ 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 ipython_ development repo.  Your ``master`` then will follow
+  the main ipython_ 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 ipython_.  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
+
+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?`_. See also the `git commit`_ manual
+   page.
+#. 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/ipython``.
+#. 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 `ipython mailing list`_, asking for
+   review.  The URL will look something like:
+   ``http://github.com/your-user-name/ipython/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/ipython.git``.
+#. Click on the 'Pull request' button:
+
+   .. image:: pull_button.png
+
+   Enter a message; we suggest you select only ``ipython`` as the
+   recipient.  The message will go to the `ipython mailing list`_.  Please
+   feel free to add others from the list as you like.
+
+Merging from trunk
+==================
+
+This updates your code from the upstream `ipython 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 ipython into your account, as from :ref:`forking`.
+
+Then, go to your forked repository github page, say
+``http://github.com/your-user-name/ipython``
+
+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 [e-mail]:your-user-name/ipython.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.txt

docs/source/development/gitwash/dot2_dot3.txt

@@ -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).

docs/source/development/gitwash/following_latest.txt

@@ -0,0 +1,36
+.. _following-latest:
+
+=============================
+ Following the latest source
+=============================
+
+These are the instructions if you just want to follow the latest
+*ipython* 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/ipython/ipython.git
+
+You now have a copy of the code tree in the new ``ipython`` directory.
+
+Updating the code
+=================
+
+From time to time you may want to pull down the latest code.  Do this with::
+
+   cd ipython
+   git pull
+
+The tree in ``ipython`` will now have the latest changes from the initial
+repository.
+
+.. include:: git_links.txt

docs/source/development/gitwash/forking_hell.txt

@@ -0,0 +1,33
+.. _forking:
+
+==========================================
+Making your own copy (fork) of ipython
+==========================================
+
+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 ipython_ 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 ipython_
+=========================================
+
+#. Log into your github_ account.
+#. Go to the ipython_ github home at `ipython 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 ipython_.
+
+.. include:: git_links.txt
+

docs/source/development/gitwash/git_development.txt

@@ -0,0 +1,16
+.. _git-development:
+
+=====================
+ Git for development
+=====================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   forking_hell
+   set_up_fork
+   configure_git
+   development_workflow
+   

docs/source/development/gitwash/git_install.txt

@@ -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.txt

docs/source/development/gitwash/git_intro.txt

@@ -0,0 +1,18
+==============
+ Introduction
+==============
+
+These pages describe a git_ and github_ workflow for the ipython_
+project.
+
+There are several different workflows here, for different ways of
+working with *ipython*.
+
+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.txt

docs/source/development/gitwash/git_links.txt

@@ -0,0 +1,67
+.. 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 mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
+
+.. nipy
+.. _dipy: http://nipy.org/dipy
+.. _`dipy github`: http://github.com/Garyfallidis/dipy
+.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. 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
+.. _git management: http://kerneltrap.org/Linux/Git_Management
+.. _linux git workflow: http://www.mail-archive.com/[e-mail]/msg39091.html
+.. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html

docs/source/development/gitwash/git_resources.txt

@@ -0,0 +1,57
+.. _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
+* Fernando Perez' git page - `Fernando's git page`_ - many links and tips
+* A good but technical page on `git concepts`_
+* Th `git parable`_ is an easy read explaining the concepts behind git.
+* `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.txt

docs/source/development/gitwash/index.txt

@@ -0,0 +1,18
+.. _using-git:
+
+Working with *ipython* source code
+======================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   git_intro
+   git_install
+   following_latest
+   patching
+   git_development
+   git_resources
+
+

docs/source/development/gitwash/patching.txt

@@ -0,0 +1,123
+================
+ Making a patch
+================
+
+You've discovered a bug or something else you want to change in ipython_ - 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 [e-mail]
+   git config --global user.name "Your Name Comes Here"
+   # get the repository if you don't have it
+   git clone git://github.com/ipython/ipython.git
+   # make a branch for your patching
+   cd ipython
+   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 `ipython 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 [e-mail]
+      git config --global user.name "Your Name Comes Here"
+
+#. If you don't already have one, clone a copy of the ipython_ repository::
+
+      git clone git://github.com/ipython/ipython.git
+      cd ipython
+
+#. 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 `ipython 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 ipython_ 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 [e-mail]:your-user-name/ipython.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.txt

docs/source/development/gitwash/set_up_fork.txt

@@ -0,0 +1,68
+.. _set-up-fork:
+
+==================
+ Set up your fork
+==================
+
+First you follow the instructions for :ref:`forking`. 
+
+Overview
+========
+
+::
+
+   git clone [e-mail]/your-user-name/ipython.git
+   cd ipython
+   git remote add upstream git://github.com/ipython/ipython.git
+
+In detail
+=========
+
+Clone your fork
+---------------
+
+#. Clone your fork to the local computer with ``git clone
+   [e-mail]:your-user-name/ipython.git``
+#. Investigate.  Change directory to your new repo: ``cd ipython``. 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 `ipython github`_ repository, so
+   you can merge in changes from trunk.
+
+.. _linking-to-upstream:
+
+Linking your repository to the upstream repo
+--------------------------------------------
+
+::
+
+   cd ipython
+   git remote add upstream git://github.com/ipython/ipython.git
+
+``upstream`` here is just the arbitrary name we're using to refer to the
+main ipython_ repository at `ipython 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/ipython/ipython.git (fetch)
+   upstream	git://github.com/ipython/ipython.git (push)
+   origin	[e-mail]:your-user-name/ipython.git (fetch)
+   origin	[e-mail]:your-user-name/ipython.git (push)
+
+.. include:: git_links.txt
+

docs/source/development/messaging.txt

@@ -0,0 +1,106
+=====================
+Message Specification
+=====================
+
+Note: not all of these have yet been fully fleshed out, but the key ones are,
+see kernel and frontend files for actual implementation details.
+
+General Message Format
+=====================
+
+General message format::
+
+    {
+        header : { 'msg_id' : 10,    # start with 0
+	           'username' : 'name',
+		   'session' : uuid
+		   },
+	parent_header : dict,
+        msg_type : 'string_message_type',
+        content : blackbox_dict , # Must be a dict
+    }
+
+Side effect: (PUB/SUB)
+======================
+
+# msg_type = 'stream'::
+
+    content = {
+	name : 'stdout',
+	data : 'blob',
+    }
+
+# msg_type = 'pyin'::
+
+    content = {
+	code = 'x=1',
+    }
+
+# msg_type = 'pyout'::
+
+    content = {
+	data = 'repr(obj)',
+	prompt_number = 10
+    }
+
+# msg_type = 'pyerr'::
+
+    content = {
+	traceback : 'full traceback',
+	exc_type : 'TypeError',
+	exc_value :  'msg'
+    }
+
+# msg_type = 'file':
+    content = {
+	path = 'cool.jpg',
+	data : 'blob'
+    }
+
+Request/Reply
+=============
+
+Execute
+-------
+
+Request:
+
+# msg_type = 'execute_request'::
+
+    content = {
+	code : 'a = 10',
+    }
+
+Reply:
+
+# msg_type = 'execute_reply'::
+
+    content = {
+      'status' : 'ok' OR 'error' OR 'abort'
+      # data depends on status value
+    }
+
+Complete
+--------
+
+# msg_type = 'complete_request'::
+
+    content = {
+	text : 'a.f',    # complete on this
+	line : 'print a.f'    # full line
+    }
+
+# msg_type = 'complete_reply'::
+
+    content = {
+	matches : ['a.foo', 'a.bar']
+    }
+
+Control
+-------
+
+# msg_type = 'heartbeat'::
+
+    content = {
+    # XXX - unfinished
+    }

tools/gitwash_dumper.py

@@ -0,0 +1,151
+#!/usr/bin/env python
+''' Checkout gitwash repo into directory and do search replace on name '''
+
+import os
+from os.path import join as pjoin
+import shutil
+import sys
+import re
+import glob
+import fnmatch
+import tempfile
+from subprocess import call
+
+
+verbose = False
+
+
+def clone_repo(url, branch):
+    cwd = os.getcwd()
+    tmpdir = tempfile.mkdtemp()
+    try:
+        cmd = 'git clone %s %s' % (url, tmpdir)
+        call(cmd, shell=True)
+        os.chdir(tmpdir)
+        cmd = 'git checkout %s' % branch
+        call(cmd, shell=True)
+    except:
+        shutil.rmtree(tmpdir)
+        raise
+    finally:
+        os.chdir(cwd)
+    return tmpdir
+
+
+def cp_files(in_path, globs, out_path):
+    try:
+        os.makedirs(out_path)
+    except OSError:
+        pass
+    out_fnames = []
+    for in_glob in globs:
+        in_glob_path = pjoin(in_path, in_glob)
+        for in_fname in glob.glob(in_glob_path):
+            out_fname = in_fname.replace(in_path, out_path)
+            pth, _ = os.path.split(out_fname)
+            if not os.path.isdir(pth):
+                os.makedirs(pth)
+            shutil.copyfile(in_fname, out_fname)
+            out_fnames.append(out_fname)
+    return out_fnames
+
+
+def filename_search_replace(sr_pairs, filename, backup=False):
+    ''' Search and replace for expressions in files
+
+    '''
+    in_txt = open(filename, 'rt').read(-1)
+    out_txt = in_txt[:]
+    for in_exp, out_exp in sr_pairs:
+        in_exp = re.compile(in_exp)
+        out_txt = in_exp.sub(out_exp, out_txt)
+    if in_txt == out_txt:
+        return False
+    open(filename, 'wt').write(out_txt)
+    if backup:
+        open(filename + '.bak', 'wt').write(in_txt)
+    return True
+
+        
+def copy_replace(replace_pairs,
+                 out_path,
+                 repo_url,
+                 repo_branch = 'master',
+                 cp_globs=('*',),
+                 rep_globs=('*',),
+                 renames = ()):
+    repo_path = clone_repo(repo_url, repo_branch)
+    try:
+        out_fnames = cp_files(repo_path, cp_globs, out_path)
+    finally:
+        shutil.rmtree(repo_path)
+    renames = [(re.compile(in_exp), out_exp) for in_exp, out_exp in renames]
+    fnames = []
+    for rep_glob in rep_globs:
+        fnames += fnmatch.filter(out_fnames, rep_glob)
+    if verbose:
+        print '\n'.join(fnames)
+    for fname in fnames:
+        filename_search_replace(replace_pairs, fname, False)
+        for in_exp, out_exp in renames:
+            new_fname, n = in_exp.subn(out_exp, fname)
+            if n:
+                os.rename(fname, new_fname)
+                break
+
+            
+USAGE = ''' <output_directory> <project_name>
+
+If not set with options, the repository name is the same as the <project
+name>
+
+If not set with options, the main github user is the same as the
+repository name.'''
+
+
+GITWASH_CENTRAL = 'git://github.com/matthew-brett/gitwash.git'
+GITWASH_BRANCH = 'master'
+
+
+if __name__ == '__main__':
+    from optparse import OptionParser
+    parser = OptionParser()
+    parser.set_usage(parser.get_usage().strip() + USAGE)
+    parser.add_option("--repo-name", dest="repo_name",
+                      help="repository name - e.g. nitime",
+                      metavar="REPO_NAME")
+    parser.add_option("--github-user", dest="main_gh_user",
+                      help="github username for main repo - e.g fperez",
+                      metavar="MAIN_GH_USER")
+    parser.add_option("--gitwash-url", dest="gitwash_url",
+                      help="URL to gitwash repository - default %s"
+                      % GITWASH_CENTRAL, 
+                      default=GITWASH_CENTRAL,
+                      metavar="GITWASH_URL")
+    parser.add_option("--gitwash-branch", dest="gitwash_branch",
+                      help="branch in gitwash repository - default %s"
+                      % GITWASH_BRANCH,
+                      default=GITWASH_BRANCH,
+                      metavar="GITWASH_BRANCH")
+    parser.add_option("--source-suffix", dest="source_suffix",
+                      help="suffix of ReST source files - default '.rst'",
+                      default='.rst',
+                      metavar="SOURCE_SUFFIX")
+    (options, args) = parser.parse_args()
+    if len(args) < 2:
+        parser.print_help()
+        sys.exit()
+    out_path, project_name = args
+    if options.repo_name is None:
+        options.repo_name = project_name
+    if options.main_gh_user is None:
+        options.main_gh_user = options.repo_name
+    copy_replace((('PROJECTNAME', project_name),
+                  ('REPONAME', options.repo_name),
+                  ('MAIN_GH_USER', options.main_gh_user)),
+                 out_path,
+                 options.gitwash_url,
+                 options.gitwash_branch,
+                 cp_globs=(pjoin('gitwash', '*'),),
+                 rep_globs=('*.rst',),
+                 renames=(('\.rst$', options.source_suffix),))

docs/Makefile

@@ -29,6 +29,7 help:
 	@echo "pdf          latex and then runs the PDF generation"
 	@echo "all          html and pdf"
 	@echo "dist         all, and then puts the results in dist/"
+	@echo "gitwash-update update git workflow from source repo"
 
 clean:
 	-rm -rf build/* dist/* $(SRCDIR)/api/generated
@@ -93,3 +94,7 linkcheck:
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.txt."
+
+gitwash-update:
+	python ../tools/gitwash_dumper.py source/development ipython
+	cd source/development/gitwash && rename 's/.rst/.txt/' *.rst

docs/source/development/contributing.txt

@@ -7,177 +7,20 How to contribute to IPython
 Overview
 ========
 
-IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
+IPython development is done using Git [Git]_ and Github.com [Github.com]_.
 This makes it easy for people to contribute to the development of IPython.
 There are several ways in which you can join in.
 
-If you have a small change that you want to contribute, you can edit your
-Bazaar checkout of IPython (see below) in-place, and ask Bazaar for the
-differences:
-
-.. code-block:: bash
-
-    $ cd /path/to/your/copy/of/ipython
-    $ bzr diff > my_fixes.diff
-
-This produces a patch file with your fixes, which we can apply to the source
-tree. This file should then be attached to a ticket in our `bug tracker
-<https://bugs.launchpad.net/ipython>`_, indicating what it does.
-
-This model of creating small, self-contained patches works very well and there
-are open source projects that do their entire development this way. However,
-in IPython we have found that for tracking larger changes, making use of
-Bazaar's full capabilities in conjunction with Launchpad's code hosting
-services makes for a much better experience.
-
-Making your own branch of IPython allows you to refine your changes over time,
-track the development of the main team, and propose your own full version of
-the code for others to use and review, with a minimum amount of fuss. The next
-parts of this document will explain how to do this.
-
-Install Bazaar and create a Launchpad account
----------------------------------------------
-
-First make sure you have installed Bazaar (see their `website
-<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
-you, try the following:
-
-.. code-block:: bash
-
-    $ bzr whoami
-    Joe Coder <[e-mail]>
-
-This should display your name and email. Next, you will want to create an
-account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
-ssh keys. For more information of setting up your ssh keys, see `this link
-<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.
-
-Get the main IPython branch from Launchpad
-------------------------------------------
-
-Now, you can get a copy of the main IPython development branch (we call this
-the "trunk"):
-
-.. code-block:: bash
-
-    $ bzr branch lp:ipython
-
-Create a working branch
------------------------
-
-When working on IPython, you won't actually make edits directly to the
-:file:`lp:ipython` branch. Instead, you will create a separate branch for your
-changes. For now, let's assume you want to do your work in a branch named
-"ipython-mybranch". Create this branch by doing:
-
-.. code-block:: bash
-
-    $ bzr branch ipython ipython-mybranch
-
-When you actually create a branch, you will want to give it a name that
-reflects the nature of the work that you will be doing in it, like
-"install-docs-update".
-
-Make edits in your working branch
----------------------------------
-
-Now you are ready to actually make edits in your :file:`ipython-mybranch`
-branch. Before doing this, it is helpful to install this branch so you can
-test your changes as you work. This is easiest if you have setuptools
-installed. Then, just do:
-
-.. code-block:: bash
-
-    $ cd ipython-mybranch
-    $ python setupegg.py develop
-
-Now, make some changes. After a while, you will want to commit your changes.
-This let's Bazaar know that you like the changes you have made and gives you
-an opportunity to keep a nice record of what you have done. This looks like
-this:
-
-.. code-block:: bash
-
-    $ ...do work in ipython-mybranch...
-    $ bzr commit -m "the commit message goes here"
-
-Please note that since we now don't use an old-style linear ChangeLog (that
-tends to cause problems with distributed version control systems), you should
-ensure that your log messages are reasonably detailed.  Use a docstring-like
-approach in the commit messages (including the second line being left
-*blank*)::
-
-  Single line summary of  changes being committed.
-
-  * more details when warranted ...
-  * including crediting outside contributors if they sent the
-    code/bug/idea!
-
-As you work, you will repeat this edit/commit cycle many times. If you work on
-your branch for a long time, you will also want to get the latest changes from
-the :file:`lp:ipython` branch. This can be done with the following sequence of
-commands:
-
-.. code-block:: bash
-
-    $ ls
-    ipython
-    ipython-mybranch
-    
-    $ cd ipython
-    $ bzr pull
-    $ cd ../ipython-mybranch
-    $ bzr merge ../ipython
-    $ bzr commit -m "Merging changes from trunk"
-
-Post your branch and request a code review
-------------------------------------------
-
-Once you are done with your edits, you should post your branch on Launchpad so
-that other IPython developers can review the changes and help you merge your
-changes into the main development branch. To post your branch on Launchpad,
-do:
-
-.. code-block:: bash
-
-    $ cd ipython-mybranch
-    $ bzr push lp:~yourusername/ipython/ipython-mybranch
-
-Then, go to the `IPython Launchpad site <http://www.launchpad.net/ipython>`_,
-and you should see your branch under the "Code" tab. If you click on your
-branch, you can provide a short description of the branch as well as mark its
-status. Most importantly, you should click the link that reads "Propose for
-merging into another branch". What does this do?
-
-This let's the other IPython developers know that your branch is ready to be
-reviewed and merged into the main development branch. During this review
-process, other developers will give you feedback and help you get your code
-ready to be merged. What types of things will we be looking for:
-
-* All code is documented.  How to document your code is described in 
-  :ref:`this section <documenting-ipython>`.
-* All code has tests.  How to write and run tests is described in 
-  :ref:`this section <testing>`.
-* The entire IPython test suite passes.
-
-You should also provide us with a list of changes that your branch contains.
-See the :ref:`What's new <whatsnew_index>` section of our documentation
-(:file:`docs/source/whatsnew`) for details on the format and content of this.
-
-Once your changes have been reviewed and approved, someone will merge them
-into the main development branch.
-
 
 Merging a branch into trunk
 ===========================
 
 Core developers, who ultimately merge any approved branch (from themselves,
 another developer, or any third-party contribution) will typically use
-:command:`bzr merge` to merge the branch into the trunk and push it to the
-main Launchpad site. There are a number of things to keep in mind when doing
-this, so that the project history is easy to understand in the long
-run, and that generating release notes is as painless and accurate as
-possible.
+:command:`git merge` to merge the branch into the trunk and push it to the main
+Git repository. There are a number of things to keep in mind when doing this,
+so that the project history is easy to understand in the long run, and that
+generating release notes is as painless and accurate as possible.
 
 * When you merge any non-trivial functionality (from one small bug fix to a
   big feature branch), please remember to always edit the appropriate file in
@@ -197,13 +40,13 possible.
   committing something that is completely (or almost so) a third-party
   contribution, do the commit as::
   
-    $ bzr commit --author="Someone Else"
+    $ git commit --author="Someone Else"
 
   This way it will show that name separately in the log, which makes it even
   easier to spot. Obviously we often rework third party contributions
-  extensively, but this is still good to keep in mind for cases when we don't
+  extensively ,but this is still good to keep in mind for cases when we don't
   touch the code too much.
 
 
-.. [Bazaar] Bazaar. http://bazaar-vcs.org/
-.. [Launchpad] Launchpad. http://www.launchpad.net/ipython
+.. [Git] The Git version control system. 
+.. [Github.com] Github.com. http://github.com

docs/source/development/index.txt

@@ -8,6 +8,7 IPython developer's guide
    :maxdepth: 1
 
    contributing.txt
+   gitwash/index.txt
    coding_guide.txt
    doc_guide.txt
    testing.txt