Updated docs to reflect changes in our test running.

docs/source/changes.txt

@@ -1,577 +1,544 b''
 .. Developers should add in this file, during each release cycle, information
 .. about important changes they've made, in a summary format that's meant for
 .. end users.  For each release we normally have three sections: features,  bug
 .. fixes and api breakage.
 .. Please remember to credit the authors of the contributions by name,
 .. especially when they are new users or developers who do not regularly
 .. participate  in IPython's development.
 
 .. _changes:
 
 ==========
 What's new
 ==========
 
-.. contents::
-..
-    1  Release dev
-      1.1  New features
-      1.2  Bug fixes
-      1.3  Backwards incompatible changes
-    2  Release 0.10
-      2.1  New features
-      2.2  Bug fixes
-      2.3  Backwards incompatible changes
-    3  Release 0.9.1
-    4  Release 0.9
-      4.1  New features
-      4.2  Bug fixes
-      4.3  Backwards incompatible changes
-      4.4  Changes merged in from IPython1
-        4.4.1  New features
-        4.4.2  Bug fixes
-        4.4.3  Backwards incompatible changes
-    5  Release 0.8.4
-    6  Release 0.8.3
-    7  Release 0.8.2
-    8  Older releases
-..
-
-Release dev
-===========
-
-New features
-------------
-
-Bug fixes
----------
-
-Backwards incompatible changes
-------------------------------
-
-
 Release 0.10
 ============
 
 This release brings months of slow but steady development, and will be the last
 before a major restructuring and cleanup of IPython's internals that is already
 under way.  For this reason, we hope that 0.10 will be a stable and robust
 release so that while users adapt to some of the API changes that will come
 with the refactoring that will become IPython 0.11, they can safely use 0.10 in
 all existing projects with minimal changes (if any).
 
 IPython 0.10 is now a medium-sized project, with roughly (as reported by David
 Wheeler's :command:`sloccount` utility) 40750 lines of Python code, and a diff
 between 0.9.1 and this release that contains almost 28000 lines of code and
 documentation.  Our documentation, in PDF format, is a 495-page long PDF
 document (also available in HTML format, both generated from the same sources).
 
 Many users and developers contributed code, features, bug reports and ideas to
 this release.  Please do not hesitate in contacting us if we've failed to
 acknowledge your contribution here.  In particular, for this release we have
 contribution from the following people, a mix of new and regular names (in
 alphabetical order by first name):
 
 * Alexander Clausen: fix #341726.
 * Brian Granger: lots of work everywhere (features, bug fixes, etc).
 * Daniel Ashbrook: bug report on MemoryError during compilation, now fixed.
 * Darren Dale: improvements to documentation build system, feedback, design
   ideas.
 * Fernando Perez: various places.
 * Gaël Varoquaux: core code, ipythonx GUI, design discussions, etc. Lots...
 * John Hunter: suggestions, bug fixes, feedback.
 * Jorgen Stenarson: work on many fronts, tests, fixes, win32 support, etc.
 * Laurent Dufréchou: many improvements to ipython-wx standalone app.
 * Lukasz Pankowski: prefilter, `%edit`, demo improvements.
 * Matt Foster: TextMate support in `%edit`.
 * Nathaniel Smith: fix #237073.
 * Pauli Virtanen: fixes and improvements to extensions, documentation.
 * Prabhu Ramachandran: improvements to `%timeit`.
 * Robert Kern: several extensions.
 * Sameer D'Costa: help on critical bug #269966.
 * Stephan Peijnik: feedback on Debian compliance and many man pages.
+* Steven Bethard: we are now shipping his :mod:`argparse` module.
 * Tom Fetherston: many improvements to :mod:`IPython.demo` module.
 * Ville Vainio: lots of work everywhere (features, bug fixes, etc).
 * Vishal Vasta: ssh support in ipcluster.
 * Walter Doerwald: work on the :mod:`IPython.ipipe` system.
 
 Below we give an overview of new features, bug fixes and backwards-incompatible
 changes.  For a detailed account of every change made, feel free to view the
 project log with :command:`bzr log`.
 
 New features
 ------------
 
 * New `%paste` magic automatically extracts current contents of clipboard and
   pastes it directly, while correctly handling code that is indented or
   prepended with `>>>` or `...` python prompt markers.  A very useful new
   feature contributed by Robert Kern.
 
 * IPython 'demos', created with the :mod:`IPython.demo` module, can now be
   created from files on disk or strings in memory.  Other fixes and
   improvements to the demo system, by Tom Fetherston.
 
 * Added :func:`find_cmd` function to :mod:`IPython.platutils` module, to find
   commands in a cross-platform manner.
 
 * Many improvements and fixes to Gaël Varoquaux's :command:`ipythonx`, a
   WX-based lightweight IPython instance that can be easily embedded in other WX
   applications.  These improvements have made it possible to now have an
   embedded IPython in Mayavi and other tools.
 
 * :class:`MultiengineClient` objects now have a :meth:`benchmark` method.
 
 * The manual now includes a full set of auto-generated API documents from the
   code sources, using Sphinx and some of our own support code.  We are now
   using the `Numpy Documentation Standard`_  for all docstrings, and we have
   tried to update as many existing ones as possible to this format.
 
-.. _Numpy Documentation Standard: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
-
 * The new :mod:`IPython.Extensions.ipy_pretty` extension by Robert Kern
   provides configurable pretty-printing.
 
 * Many improvements to the :command:`ipython-wx` standalone WX-based IPython
   application by Laurent Dufréchou.  It can optionally run in a thread, and
   this can be toggled at runtime (allowing the loading of Matplotlib in a
   running session without ill effects).
 
 * IPython includes a copy of Steven Bethard's argparse_ in the
   :mod:`IPython.external` package, so we can use it internally and it is also
   available to any IPython user.  By installing it in this manner, we ensure
   zero conflicts with any system-wide installation you may already have while
-  minimizing external dependencies for new users.
+  minimizing external dependencies for new users.  In IPython 0.10, We ship
+  argparse version 1.0.
 
 * An improved and much more robust test suite, that runs groups of tests in
   separate subprocesses using either Nose or Twisted's :command:`trial` runner
   to ensure proper management of Twisted-using code.  The test suite degrades
   gracefully if optional dependencies are not available, so that the
   :command:`iptest` command can be run with only Nose installed and nothing
   else.  We also have more and cleaner test decorators to better select tests
   depending on runtime conditions, do setup/teardown, etc.
 
 * The new ipcluster now has a fully working ssh mode that should work on
   Linux, Unix and OS X.  Thanks to Vishal Vatsa for implementing this!
 
 * The wonderful TextMate editor can now be used with %edit on OS X.  Thanks
   to Matt Foster for this patch.
 
 * The documentation regarding parallel uses of IPython, including MPI and PBS,
   has been significantly updated and improved.
 
 * The developer guidelines in the documentation have been updated to explain
   our workflow using :command:`bzr` and Launchpad.
   
 * Fully refactored :command:`ipcluster` command line program for starting
   IPython clusters.  This new version is a complete rewrite and 1) is fully
   cross platform (we now use Twisted's process management), 2) has much
   improved performance, 3) uses subcommands for different types of clusters, 4)
   uses argparse for parsing command line options, 5) has better support for
   starting clusters using :command:`mpirun`, 6) has experimental support for
   starting engines using PBS.  It can also reuse FURL files, by appropriately
   passing options to its subcommands.  However, this new version of ipcluster
   should be considered a technology preview.  We plan on changing the API in
   significant ways before it is final.
 
-* The :mod:`argparse` module has been added to :mod:`IPython.external`.
-
 * Full description of the security model added to the docs.
 
 * cd completer: show bookmarks if no other completions are available.
 
 * sh profile: easy way to give 'title' to prompt: assign to variable
   '_prompt_title'. It looks like this::
       
         [~]|1> _prompt_title = 'sudo!'
         sudo![~]|2>
 
 * %edit: If you do '%edit pasted_block', pasted_block variable gets updated
   with new data (so repeated editing makes sense)
 
+.. _Numpy Documentation Standard: http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard
+
+.. _argparse: http://code.google.com/p/argparse/
+
 Bug fixes
 ---------
 
 * Fix #368719, removed top-level debian/ directory to make the job of Debian
   packagers easier.
   
 * Fix #291143 by including man pages contributed by Stephan Peijnik from the
   Debian project.
 
 * Fix #358202, effectively a race condition, by properly synchronizing file
   creation at cluster startup time.
 
 * `%timeit` now handles correctly functions that take a long time to execute
   even the first time, by not repeating them.
 
 * Fix #239054, releasing of references after exiting.
 
 * Fix #341726, thanks to Alexander Clausen.
 
 * Fix #269966.  This long-standing and very difficult bug (which is actually a
   problem in Python itself) meant long-running sessions would inevitably grow
   in memory size, often with catastrophic consequences if users had large
   objects in their scripts.  Now, using `%run` repeatedly should not cause any
   memory leaks.  Special thanks to John Hunter and Sameer D'Costa for their
   help with this bug.
 
 * Fix #295371, bug in `%history`.
 
 * Improved support for py2exe.
 
 * Fix #270856: IPython hangs with PyGTK
 
 * Fix #270998: A magic with no docstring breaks the '%magic magic'
 
 * fix #271684: -c startup commands screw up raw vs. native history
 
 * Numerous bugs on Windows with the new ipcluster have been fixed.
 
 * The ipengine and ipcontroller scripts now handle missing furl files
   more gracefully by giving better error messages.
 
 * %rehashx: Aliases no longer contain dots. python3.0 binary
   will create alias python30. Fixes:
   #259716 "commands with dots in them don't work"
 
 * %cpaste: %cpaste -r repeats the last pasted block.
   The block is assigned to pasted_block even if code
   raises exception.
 
 * Bug #274067 'The code in get_home_dir is broken for py2exe' was
   fixed.
 
+* Many other small bug fixes not listed here by number (see the bzr log for
+  more info).
+  
 Backwards incompatible changes
 ------------------------------
 
 * `ipykit` and related files were unmaintained and have been removed.
 
 * The :func:`IPython.genutils.doctest_reload` does not actually call
   `reload(doctest)` anymore, as this was causing many problems with the test
   suite.  It still resets `doctest.master` to None.
 
 * While we have not deliberately broken Python 2.4 compatibility, only minor
   testing was done with Python 2.4, while 2.5 and 2.6 were fully tested.  But
   if you encounter problems with 2.4, please do report them as bugs.
 
 * The :command:`ipcluster` now requires a mode argument; for example to start a
   cluster on the local machine with 4 engines, you must now type::
 
     $ ipcluster local -n 4
 
 * The controller now has a ``-r`` flag that needs to be used if you want to
   reuse existing furl files.  Otherwise they are deleted (the default).
 
 * Remove ipy_leo.py. You can use :command:`easy_install ipython-extension` to
   get it.  (done to decouple it from ipython release cycle)
 
 
 Release 0.9.1
 =============
 
 This release was quickly made to restore compatibility with Python 2.4, which
 version 0.9 accidentally broke.  No new features were introduced, other than
 some additional testing support for internal use.
 
 
 Release 0.9
 ===========
 
 New features
 ------------
 
 * All furl files and security certificates are now put in a read-only
   directory named ~./ipython/security.
 
 * A single function :func:`get_ipython_dir`, in :mod:`IPython.genutils` that
   determines the user's IPython directory in a robust manner.
 
 * Laurent's WX application has been given a top-level script called
   ipython-wx, and it has received numerous fixes. We expect this code to be
   architecturally better integrated with Gael's WX 'ipython widget' over the
   next few releases.
 
 * The Editor synchronization work by Vivian De Smedt has been merged in.  This
   code adds a number of new editor hooks to synchronize with editors under
   Windows.
 
 * A new, still experimental but highly functional, WX shell by Gael Varoquaux.
   This work was sponsored by Enthought, and while it's still very new, it is
   based on a more cleanly organized arhictecture of the various IPython
   components. We will continue to develop this over the next few releases as a
   model for GUI components that use IPython.
 
 * Another GUI frontend, Cocoa based (Cocoa is the OSX native GUI framework),
   authored by Barry Wark.  Currently the WX and the Cocoa ones have slightly
   different internal organizations, but the whole team is working on finding
   what the right abstraction points are for a unified codebase.
 
 * As part of the frontend work, Barry Wark also implemented an experimental
   event notification system that various ipython components can use.  In the
   next release the implications and use patterns of this system regarding the
   various GUI options will be worked out.
 
 * IPython finally has a full test system, that can test docstrings with
   IPython-specific functionality.  There are still a few pieces missing for it
   to be widely accessible to all users (so they can run the test suite at any
   time and report problems), but it now works for the developers.  We are
   working hard on continuing to improve it, as this was probably IPython's
   major Achilles heel (the lack of proper test coverage made it effectively
   impossible to do large-scale refactoring).  The full test suite can now
   be run using the :command:`iptest` command line program.
 
 * The notion of a task has been completely reworked.  An `ITask` interface has
   been created.  This interface defines the methods that tasks need to
   implement.  These methods are now responsible for things like submitting
   tasks and processing results.  There are two basic task types:
   :class:`IPython.kernel.task.StringTask` (this is the old `Task` object, but
   renamed) and the new :class:`IPython.kernel.task.MapTask`, which is based on
   a function.
 
 * A new interface, :class:`IPython.kernel.mapper.IMapper` has been defined to
   standardize the idea of a `map` method.  This interface has a single `map`
   method that has the same syntax as the built-in `map`.  We have also defined
   a `mapper` factory interface that creates objects that implement
   :class:`IPython.kernel.mapper.IMapper` for different controllers.  Both the
   multiengine and task controller now have mapping capabilties.
 
 * The parallel function capabilities have been reworks.  The major changes are
   that i) there is now an `@parallel` magic that creates parallel functions,
   ii) the syntax for mulitple variable follows that of `map`, iii) both the
   multiengine and task controller now have a parallel function implementation.
 
 * All of the parallel computing capabilities from `ipython1-dev` have been
   merged into IPython proper.  This resulted in the following new subpackages:
   :mod:`IPython.kernel`, :mod:`IPython.kernel.core`, :mod:`IPython.config`,
   :mod:`IPython.tools` and :mod:`IPython.testing`.
 
 * As part of merging in the `ipython1-dev` stuff, the `setup.py` script and
   friends have been completely refactored.  Now we are checking for
   dependencies using the approach that matplotlib uses.
 
 * The documentation has been completely reorganized to accept the 
   documentation from `ipython1-dev`.
 
 * We have switched to using Foolscap for all of our network protocols in
   :mod:`IPython.kernel`.  This gives us secure connections that are both
   encrypted and authenticated.
 
 * We have a brand new `COPYING.txt` files that describes the IPython license
   and copyright. The biggest change is that we are putting "The IPython
   Development Team" as the copyright holder. We give more details about
   exactly what this means in this file. All developer should read this and use
   the new banner in all IPython source code files.
 
 * sh profile: ./foo runs foo as system command, no need to do !./foo anymore
 
 * String lists now support ``sort(field, nums = True)`` method (to easily sort
   system command output). Try it with ``a = !ls -l ; a.sort(1, nums=1)``.
 
 * '%cpaste foo' now assigns the pasted block as string list, instead of string
 
 * The ipcluster script now run by default with no security.  This is done
   because the main usage of the script is for starting things on localhost.
   Eventually when ipcluster is able to start things on other hosts, we will put
   security back.
 
 * 'cd --foo' searches directory history for string foo, and jumps to that dir.
   Last part of dir name is checked first. If no matches for that are found,
   look at the whole path.
 
   
 Bug fixes
 ---------
 
 * The Windows installer has been fixed.  Now all IPython scripts have ``.bat``
   versions created.  Also, the Start Menu shortcuts have been updated.
 
 * The colors escapes in the multiengine client are now turned off on win32 as
   they don't print correctly.
 
 * The :mod:`IPython.kernel.scripts.ipengine` script was exec'ing
   mpi_import_statement incorrectly, which was leading the engine to crash when
   mpi was enabled.
 
 * A few subpackages had missing ``__init__.py`` files.
 
 * The documentation is only created if Sphinx is found.  Previously, the
   ``setup.py`` script would fail if it was missing.
 
 * Greedy ``cd`` completion has been disabled again (it was enabled in 0.8.4) as
   it caused problems on certain platforms.
           
 
 Backwards incompatible changes
 ------------------------------
 
 * The ``clusterfile`` options of the :command:`ipcluster` command has been
   removed as it was not working and it will be replaced soon by something much
   more robust.
 
 * The :mod:`IPython.kernel` configuration now properly find the user's
   IPython directory.
 
 * In ipapi, the :func:`make_user_ns` function has been replaced with
   :func:`make_user_namespaces`, to support dict subclasses in namespace
   creation.
 
 * :class:`IPython.kernel.client.Task` has been renamed
   :class:`IPython.kernel.client.StringTask` to make way for new task types.
 
 * The keyword argument `style` has been renamed `dist` in `scatter`, `gather`
   and `map`.
 
 * Renamed the values that the rename `dist` keyword argument can have from
   `'basic'` to `'b'`.
 
 * IPython has a larger set of dependencies if you want all of its capabilities.
   See the `setup.py` script for details.
 
 * The constructors for :class:`IPython.kernel.client.MultiEngineClient` and 
   :class:`IPython.kernel.client.TaskClient` no longer take the (ip,port) tuple.
   Instead they take the filename of a file that contains the FURL for that
   client.  If the FURL file is in your IPYTHONDIR, it will be found automatically
   and the constructor can be left empty.
 
 * The asynchronous clients in :mod:`IPython.kernel.asyncclient` are now created 
   using the factory functions :func:`get_multiengine_client` and 
   :func:`get_task_client`.  These return a `Deferred` to the actual client.
 
 * The command line options to `ipcontroller` and `ipengine` have changed to
   reflect the new Foolscap network protocol and the FURL files.  Please see the
   help for these scripts for details.
 
 * The configuration files for the kernel have changed because of the Foolscap
   stuff.  If you were using custom config files before, you should delete them
   and regenerate new ones.
 
 Changes merged in from IPython1
 -------------------------------
 
 New features
 ............
 
 * Much improved ``setup.py`` and ``setupegg.py`` scripts.  Because Twisted and
   zope.interface are now easy installable, we can declare them as dependencies
   in our setupegg.py script.
 
 * IPython is now compatible with Twisted 2.5.0 and 8.x.
 
 * Added a new example of how to use :mod:`ipython1.kernel.asynclient`.
 
 * Initial draft of a process daemon in :mod:`ipython1.daemon`.  This has not
   been merged into IPython and is still in `ipython1-dev`.
   
 * The ``TaskController`` now has methods for getting the queue status.
 
 * The ``TaskResult`` objects not have information about how long the task
   took to run.
   
 * We are attaching additional attributes to exceptions ``(_ipython_*)`` that 
   we use to carry additional info around.
   
 * New top-level module :mod:`asyncclient` that has asynchronous versions (that
   return deferreds) of the client classes.  This is designed to users who want
   to run their own Twisted reactor.
   
 * All the clients in :mod:`client` are now based on Twisted.  This is done by 
   running the Twisted reactor in a separate thread and using the
   :func:`blockingCallFromThread` function that is in recent versions of Twisted.
 
 * Functions can now be pushed/pulled to/from engines using
   :meth:`MultiEngineClient.push_function` and
   :meth:`MultiEngineClient.pull_function`.
 
 * Gather/scatter are now implemented in the client to reduce the work load
   of the controller and improve performance.
 
 * Complete rewrite of the IPython docuementation.  All of the documentation
   from the IPython website has been moved into docs/source as restructured
   text documents.  PDF and HTML documentation are being generated using 
   Sphinx.
 
 * New developer oriented documentation: development guidelines and roadmap. 
 
 * Traditional ``ChangeLog`` has been changed to a more useful ``changes.txt``
   file that is organized by release and is meant to provide something more
   relevant for users.
 
 Bug fixes
 .........
 
 * Created a proper ``MANIFEST.in`` file to create source distributions.
 
 * Fixed a bug in the ``MultiEngine`` interface.  Previously, multi-engine 
   actions were being collected with a :class:`DeferredList` with 
   ``fireononeerrback=1``.  This meant that methods were returning 
   before all engines had given their results.  This was causing extremely odd 
   bugs in certain cases. To fix this problem, we have 1) set 
   ``fireononeerrback=0`` to make sure all results (or exceptions) are in 
   before returning and 2) introduced a :exc:`CompositeError` exception 
   that wraps all of the engine exceptions.  This is a huge change as it means 
   that users will have to catch :exc:`CompositeError` rather than the actual
   exception.
 
 Backwards incompatible changes
 ..............................
 
 * All names have been renamed to conform to the lowercase_with_underscore
   convention.  This will require users to change references to all names like
   ``queueStatus`` to ``queue_status``.
 
 * Previously, methods like :meth:`MultiEngineClient.push` and
   :meth:`MultiEngineClient.push` used ``*args`` and ``**kwargs``.  This was
   becoming a problem as we weren't able to introduce new keyword arguments into
   the API.  Now these methods simple take a dict or sequence.  This has also
   allowed us to get rid of the ``*All`` methods like :meth:`pushAll` and
   :meth:`pullAll`.  These things are now handled with the ``targets`` keyword
   argument that defaults to ``'all'``.
 
 * The :attr:`MultiEngineClient.magicTargets` has been renamed to
   :attr:`MultiEngineClient.targets`. 
 
 * All methods in the MultiEngine interface now accept the optional keyword
   argument ``block``.
 
 * Renamed :class:`RemoteController` to :class:`MultiEngineClient` and 
   :class:`TaskController` to :class:`TaskClient`.
 
 * Renamed the top-level module from :mod:`api` to :mod:`client`.
 
 * Most methods in the multiengine interface now raise a :exc:`CompositeError`
   exception that wraps the user's exceptions, rather than just raising the raw
   user's exception.
 
 * Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class to ``push`` 
   and ``pull``.
 
   
 Release 0.8.4
 =============
 
 This was a quick release to fix an unfortunate bug that slipped into the 0.8.3
 release.  The ``--twisted`` option was disabled, as it turned out to be broken
 across several platforms.
 
 
 Release 0.8.3
 =============
   
 * pydb is now disabled by default (due to %run -d problems). You can enable
   it by passing -pydb command line argument to IPython. Note that setting
   it in config file won't work.
 
   
 Release 0.8.2
 =============
 
 * %pushd/%popd behave differently; now "pushd /foo" pushes CURRENT directory 
   and jumps to /foo. The current behaviour is closer to the documented 
   behaviour, and should not trip anyone.
 
   
 Older releases
 ==============
 
 Changes in earlier releases of IPython are described in the older file
 ``ChangeLog``.  Please refer to this document for details.
 

docs/source/development/overview.txt

@@ -1,494 +1,515 b''
 .. _development:
 
 ==============================
 IPython development guidelines
 ==============================
 
 
 Overview
 ========
 
 This document describes IPython from the perspective of developers. Most
 importantly, it gives information for people who want to contribute to the
 development of IPython. So if you want to help out, read on!
 
 How to contribute to IPython
 ============================
 
 IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
 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 send to the team, you can edit your
 bazaar checkout of IPython (see below) in-place, and ask bazaar for the
 differences::
 
     $ 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::
 
     $ 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")::
 
     $ 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::
 
     $ 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::
 
     $ 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::
 
     $ ...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::
 
     $ ls
     ipython
     ipython-mybranch
     
     $ cd ipython
     $ bzr pull
     $ cd ../ipython-mybranch
     $ bzr merge ../ipython
     $ bzr commit -m "Merging changes from trunk"
 
 Along the way, you should also run the IPython test suite.  You can do this
 using the :command:`iptest` command (which is basically a customized version of
 :command:`nosetests`)::
 
     $ cd
     $ iptest
 
 The :command:`iptest` command will also pick up and run any tests you have
 written.  See :ref:`_devel_testing` for further details on the testing system.
 
 
 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::
 
     $ cd ipython-mybranch
     $ bzr push lp:~yourusername/ipython/ipython-mybranch
 
 Then, go to the `IPython Launchpad site <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.
 * All code has tests.
 * The entire IPython test suite passes.
 
 Once your changes have been reviewed and approved, someone will merge them
 into the main development branch.
 
+
+Some notes for core developers when merging third-party contributions
+=====================================================================
+
+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
+Launcphad site.  This is a short list of things to keep in mind when doing this
+process, 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 changes_ file
+  accordingly.  This file has one main section for each release, and if you
+  edit it as you go, noting what new features, bug fixes or API changes you
+  have made, the release notes will be almost finished when they are needed
+  later.  This is much easier if done when you merge the work, rather than
+  weeks or months later by re-reading a massive Bazaar log.
+
+- When big merges are done, the practice of putting a summary commit message in
+  the merge is *extremely* useful.  It makes this kind of job much nicer,
+  because that summary log message can be almost copy/pasted without changes,
+  if it was well written, rather than dissecting the next-level messages from
+  the individual commits.
+
+- It's important that we remember to always credit who gave us something if
+  it's not the committer.  In general, we have been fairly good on this front,
+  this is just a reminder to keep things up.  As a note, if you are ever
+  committing something that is completely (or almost so) a third-party
+  contribution, do the commit as::
+
+    $ bzr 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
+  touch the code too much.
+
+
 Documentation
 =============
 
 Standalone documentation
 ------------------------
 
 All standalone documentation should be written in plain text (``.txt``) files
 using reStructuredText [reStructuredText]_ for markup and formatting. All such
 documentation should be placed in directory :file:`docs/source` of the IPython
 source tree. The documentation in this location will serve as the main source
 for IPython documentation and all existing documentation should be converted
 to this format.
 
 To build the final documentation, we use Sphinx [Sphinx]_.  Once you have
 Sphinx installed, you can build the html docs yourself by doing::
 
     $ cd ipython-mybranch/docs
     $ make html
 
 Docstring format
 ----------------
 
 Good docstrings are very important. All new code should have docstrings that
 are formatted using reStructuredText for markup and formatting, since it is
 understood by a wide variety of tools. Details about using reStructuredText
 for docstrings can be found `here
 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
 
 Additional PEPs of interest regarding documentation of code:
 
 * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
 * `Docstring Processing System Framework <http://www.python.org/peps/pep-0256.html>`_
 * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
 
 
 Coding conventions
 ==================
 
 General
 -------
 
 In general, we'll try to follow the standard Python style conventions as
 described here:
 
 * `Style Guide for Python Code  <http://www.python.org/peps/pep-0008.html>`_  
 
 
 Other comments:
 
 * In a large file, top level classes and functions should be 
   separated by 2-3 lines to make it easier to separate them visually.
 * Use 4 spaces for indentation.
 * Keep the ordering of methods the same in classes that have the same 
   methods.  This is particularly true for classes that implement an interface.
 
 Naming conventions
 ------------------
 
 In terms of naming conventions, we'll follow the guidelines from the `Style
 Guide for Python Code`_.
 
 For all new IPython code (and much existing code is being refactored), we'll
 use:
 
 * All ``lowercase`` module names.
 
 * ``CamelCase`` for class names.
 
 * ``lowercase_with_underscores`` for methods, functions, variables and
   attributes.
 
 There are, however, some important exceptions to these rules. In some cases,
 IPython code will interface with packages (Twisted, Wx, Qt) that use other
 conventions. At some level this makes it impossible to adhere to our own
 standards at all times. In particular, when subclassing classes that use other
 naming conventions, you must follow their naming conventions. To deal with
 cases like this, we propose the following policy:
 
 * If you are subclassing a class that uses different conventions, use its
   naming conventions throughout your subclass.  Thus, if you are creating a
   Twisted Protocol class, used Twisted's
   ``namingSchemeForMethodsAndAttributes.``
 
 * All IPython's official interfaces should use our conventions.  In some cases
   this will mean that you need to provide shadow names (first implement
   ``fooBar`` and then ``foo_bar = fooBar``).  We want to avoid this at all
   costs, but it will probably be necessary at times.  But, please use this
   sparingly!
 
 Implementation-specific *private* methods will use
 ``_single_underscore_prefix``. Names with a leading double underscore will
 *only* be used in special cases, as they makes subclassing difficult (such
 names are not easily seen by child classes).
 
 Occasionally some run-in lowercase names are used, but mostly for very short
 names or where we are implementing methods very similar to existing ones in a
 base class (like ``runlines()`` where ``runsource()`` and ``runcode()`` had
 established precedent).
 
 The old IPython codebase has a big mix of classes and modules prefixed with an
 explicit ``IP``. In Python this is mostly unnecessary, redundant and frowned
 upon, as namespaces offer cleaner prefixing. The only case where this approach
 is justified is for classes which are expected to be imported into external
 namespaces and a very generic name (like Shell) is too likely to clash with
 something else. We'll need to revisit this issue as we clean up and refactor
 the code, but in general we should remove as many unnecessary ``IP``/``ip``
 prefixes as possible. However, if a prefix seems absolutely necessary the more
 specific ``IPY`` or ``ipy`` are preferred.
 
 .. _devel_testing:
 
 Testing system
 ==============
 
 It is extremely important that all code contributed to IPython has tests.
 Tests should be written as unittests, doctests or as entities that the Nose
 [Nose]_ testing package will find. Regardless of how the tests are written, we
 will use Nose for discovering and running the tests. Nose will be required to
 run the IPython test suite, but will not be required to simply use IPython.
 
 Tests of Twisted using code need to follow two additional guidelines:
 
 1. Twisted using tests should be written by subclassing the :class:`TestCase`
    class that comes with :mod:`twisted.trial.unittest`. 
 
 2. All :class:`Deferred` instances that are created in the test must be
    properly chained and the final one *must* be the return value of the test
    method.
 
 When these two things are done, Nose will be able to run the tests and the
 twisted reactor will be handled correctly.
 
 Each subpackage in IPython should have its own :file:`tests` directory that
 contains all of the tests for that subpackage. This allows each subpackage to
 be self-contained.  A good convention to follow is to have a file named
 :file:`test_foo.py` for each module :file:`foo.py` in the package.  This makes
 it easy to organize the tests, though like most conventions, it's OK to break
 it if logic and common sense dictate otherwise.
 
 If a subpackage has any dependencies beyond the Python standard library, the
 tests for that subpackage should be skipped if the dependencies are not
 found. This is very important so users don't get tests failing simply because
 they don't have dependencies.  We ship a set of decorators in the
 :mod:`IPython.testing` package to tag tests that may be platform-specific or
 otherwise may have restrictions; if the existing ones don't fit your needs, add
 a new decorator in that location so other tests can reuse it.
 
 To run the IPython test suite, use the :command:`iptest` command that is
 installed with IPython (if you are using IPython in-place, without installing
 it, you can find this script in the :file:`scripts` directory)::
 
     $ iptest
 
-This command runs Nose with the proper options and extensions.  By default,
-:command:`iptest` runs the entire IPython test suite (skipping tests that may
-be platform-specific or which depend on tools you may not have).  But you can
-also use it to run only one specific test file, or a specific test function.
-For example, this will run only the :file:`test_magic` file from the test
-suite::
+This command colects all IPython tests into separate groups, and then calls
+either Nose with the proper options and extensions, or Twisted's
+:command:`trial`.  This ensures that tests that need the Twisted reactor
+management facilities execute separate of Nose.  If any individual test group
+fails, :command:`iptest` will print what you need to type so you can rerun that
+particular test group alone for debugging.
+
+By default, :command:`iptest` runs the entire IPython test
+suite (skipping tests that may be platform-specific or which depend on tools
+you may not have).  But you can also use it to run only one specific test file,
+or a specific test function.  For example, this will run only the
+:file:`test_magic` file from the test suite::
 
     $ iptest IPython.tests.test_magic
     ----------------------------------------------------------------------
     Ran 10 tests in 0.348s
 
     OK (SKIP=3)
     Deleting object: second_pass
 
 while the ``path:function`` syntax allows you to select a specific function in
 that file to run::
 
     $ iptest IPython.tests.test_magic:test_obj_del
     ----------------------------------------------------------------------
     Ran 1 test in 0.204s
 
     OK
 
 Since :command:`iptest` is based on nosetests, you can pass it any regular
 nosetests option.  For example, you can use ``--pdb`` or ``--pdb-failures`` to
 automatically activate the interactive Pdb debugger on errors or failures.  See
 the nosetests documentation for further details.
 
-.. warning::
-
-   Note that right now we have a nasty interaction between ipdoctest and
-   twisted.  Until we figure this out, please use the following instructions to
-   ensure that at least you run all the tests.
-
-Right now, if you now run::
-
-    $ iptest [any options] [any submodules]
-
-it will NOT load ipdoctest but won't cause any Twisted problems.
-
-Once you're happy that you didn't break Twisted, run::
-
-    $ iptest --with-ipdoctest [any options] [any submodules]
-
-This MAY give a Twisted AlreadyCalledError exception at the end, but it will
-also correctly load up all of the ipython-specific tests and doctests.
-
-The above can be made easier with a trivial shell alias::
-
-    $ alias iptest2='iptest --with-ipdoctest'
-
-So that you can run::
-
-    $ iptest ...
-    # Twisted happy
-    # iptest2 ...
-    # ignore possible Twisted error, this checks all the rest.
-
 
 A few tips for writing tests
 ----------------------------
 
 You can write tests either as normal test files, using all the conventions that
 Nose recognizes, or as doctests.  Note that *all* IPython functions should have
 at least one example that serves as a doctest, whenever technically feasible.
 However, example doctests should only be in the main docstring if they are *a
 good example*, i.e. if they convey useful information about the function.  If
 you simply would like to write a test as a doctest, put it in a separate test
 file and write a no-op function whose only purpose is its docstring.
 
 Note, however, that in a file named :file:`test_X`, functions whose only test
 is their docstring (as a doctest) and which have no test functionality of their
 own, should be called *doctest_foo* instead of *test_foo*, otherwise they get
 double-counted (the empty function call is counted as a test, which just
 inflates tests numbers artificially).  This restriction does not apply to
 functions in files with other names, due to how Nose discovers tests.
 
 You can use IPython examples in your docstrings.  Those can make full use of
 IPython functionality (magics, variable substitution, etc), but be careful to
 keep them generic enough that they run identically on all Operating Systems.
 
 The prompts in your doctests can be either of the plain Python ``>>>`` variety
 or ``In [1]:`` IPython style.  Since this is the IPython system, after all, we
 encourage you to use IPython prompts throughout, unless you are illustrating a
 specific aspect of the normal prompts (such as the ``%doctest_mode`` magic).
 
 If a test isn't safe to run inside the main nose process (e.g. because it loads
 a GUI toolkit), consider running it in a subprocess and capturing its output
 for evaluation and test decision later.  Here is an example of how to do it, by
 relying on the builtin ``_ip`` object that contains the public IPython api as
 defined in :mod:`IPython.ipapi`::
 
    def test_obj_del():
        """Test that object's __del__ methods are called on exit."""
        test_dir = os.path.dirname(__file__)
        del_file = os.path.join(test_dir,'obj_del.py')
        out = _ip.IP.getoutput('ipython %s' % del_file)
        nt.assert_equals(out,'object A deleted')
 
 
 
 If a doctest contains input whose output you don't want to verify identically
 via doctest (random output, an object id, etc), you can mark a docstring with
 ``#random``.  All of these test will have their code executed but no output
 checking will be done::
 
        >>> 1+3
        junk goes here...  # random
 
        >>> 1+2
        again,  anything goes #random
        if multiline, the random mark is only needed once.
 
        >>> 1+2
        You can also put the random marker at the end:
        # random
 
        >>> 1+2
        # random
        .. or at the beginning.
 
 In a case where you want an *entire* docstring to be executed but not verified
 (this only serves to check that the code runs without crashing, so it should be
 used very sparingly), you can put ``# all-random`` in the docstring.
        
 .. _devel_config:
 
 Release checklist
 =================
 
 Most of the release process is automated by the :file:`release` script in the
 :file:`tools` directory.  This is just a handy reminder for the release manager.
 
+#. First, run :file:`build_release`, which does all the file checking and
+   building that the real release script will do.  This will let you do test
+   installations, check that the build procedure runs OK, etc.  You may want to
+   disable a few things like multi-version RPM building while testing, because
+   otherwise the build takes really long.
+
 #. Run the release script, which makes the tar.gz, eggs and Win32 .exe
    installer.  It posts them to the site and registers the release with PyPI.
 
 #. Updating the website with announcements and links to the updated
    changes.txt in html form. Remember to put a short note both on the news
    page of the site and on Launcphad.
 
 #. Drafting a short release announcement with i) highlights and ii) a link to
    the html changes.txt.
 
 #. Make sure that the released version of the docs is live on the site.
 
 #. Celebrate!
 
 Porting to 3.0
 ==============
 
 There are no definite plans for porting of IPython to python 3. The major 
 issue is the dependency on twisted framework for the networking/threading 
 stuff. It is possible that it the traditional IPython interactive console 
 could be ported more easily since it has no such dependency. Here are a few
 things that will need to be considered when doing such a port especially
 if we want to have a codebase that works directly on both 2.x and 3.x.
 
 	1. The syntax for exceptions changed (PEP 3110). The old 
 	   `except exc, var` changed to `except exc as var`. At last
 	   count there was 78 occurences of this usage in the codebase.  This
 	   is  a particularly problematic issue, because it's not easy to
 	   implement it in a 2.5-compatible way.
 
 Because it is quite difficult to support simultaneously Python 2.5 and 3.x, we
 will likely at some point put out a release that requires strictly 2.6 and
 abandons 2.5 compatibility.  This will then allow us to port the code to using
 :func:`print` as a function, `except exc as var` syntax, etc.  But as of
 version 0.11 at least, we will retain Python 2.5 compatibility.
 
 
 .. [Bazaar] Bazaar. http://bazaar-vcs.org/
 .. [Launchpad] Launchpad. http://www.launchpad.net/ipython
 .. [reStructuredText] reStructuredText.  http://docutils.sourceforge.net/rst.html
 .. [Sphinx] Sphinx. http://sphinx.pocoo.org/
 .. [Nose] Nose: a discovery based unittest extension. http://code.google.com/p/python-nose/