Final doc updates for release 0.9.1.

docs/source/changes.txt

@@ -1,325 +1,334 b''
 .. _changes:
 
 ==========
 What's new
 ==========
 
 .. contents::
 ..
-    1  Release 0.9
-      1.1  New features
-      1.2  Bug fixes
-      1.3  Backwards incompatible changes
-      1.4  Changes merged in from IPython1
-        1.4.1  New features
-        1.4.2  Bug fixes
-        1.4.3  Backwards incompatible changes
-    2  Release 0.8.4
-    3  Release 0.8.3
-    4  Release 0.8.2
-    5  Older releases
+    1  Release 0.9.1
+    2  Release 0.9
+      2.1  New features
+      2.2  Bug fixes
+      2.3  Backwards incompatible changes
+      2.4  Changes merged in from IPython1
+        2.4.1  New features
+        2.4.2  Bug fixes
+        2.4.3  Backwards incompatible changes
+    3  Release 0.8.4
+    4  Release 0.8.3
+    5  Release 0.8.2
+    6  Older releases
 ..
 
 
+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/development.txt

@@ -1,426 +1,446 b''
 .. _development:
 
-==================================
+==============================
 IPython development guidelines
-==================================
-
-.. contents::
+==============================
 
 
 Overview
 ========
 
 IPython is the next generation of IPython.  It is named such for two reasons:
 
 - Eventually, IPython will become IPython version 1.0.
 - This new code base needs to be able to co-exist with the existing IPython until
   it is a full replacement for it.  Thus we needed a different name.  We couldn't
   use ``ipython`` (lowercase) as some files systems are case insensitive.
 
 There are two, no three, main goals of the IPython effort:
 
 1. Clean up the existing codebase and write lots of tests.
 2. Separate the core functionality of IPython from the terminal to enable IPython
    to be used from within a variety of GUI applications.
 3. Implement a system for interactive parallel computing.
 
 While the third goal may seem a bit unrelated to the main focus of IPython, it
 turns out that the technologies required for this goal are nearly identical
 with those required for goal two. This is the main reason the interactive
 parallel computing capabilities are being put into IPython proper. Currently
 the third of these goals is furthest along.
 
 This document describes IPython from the perspective of developers.  
 
 
 Project organization
 ====================
 
 Subpackages
 -----------
 
 IPython is organized into semi self-contained subpackages.  Each of the
 subpackages will have its own:
 
 - **Dependencies**.  One of the most important things to keep in mind in
   partitioning code amongst subpackages, is that they should be used to cleanly
   encapsulate dependencies.
   
 - **Tests**.  Each subpackage shoud have its own ``tests`` subdirectory that
   contains all of the tests for that package.  For information about writing
   tests for IPython, see the `Testing System`_ section of this document.
   
 - **Configuration**.  Each subpackage should have its own ``config``
   subdirectory that contains the configuration information for the components
   of the subpackage.  For information about how the IPython configuration
   system works, see the `Configuration System`_ section of this document.
   
 - **Scripts**.  Each subpackage should have its own ``scripts`` subdirectory
   that contains all of the command line scripts associated with the subpackage.
 
 Installation and dependencies
 -----------------------------
    
 IPython will not use `setuptools`_ for installation. Instead, we will use
 standard ``setup.py`` scripts that use `distutils`_. While there are a number a
 extremely nice features that `setuptools`_ has (like namespace packages), the
 current implementation of `setuptools`_ has performance problems, particularly
 on shared file systems. In particular, when Python packages are installed on
 NSF file systems, import times become much too long (up towards 10 seconds).
 
 Because IPython is being used extensively in the context of high performance
 computing, where performance is critical but shared file systems are common, we
 feel these performance hits are not acceptable. Thus, until the performance
 problems associated with `setuptools`_ are addressed, we will stick with plain
 `distutils`_. We are hopeful that these problems will be addressed and that we
 will eventually begin using `setuptools`_. Because of this, we are trying to
 organize IPython in a way that will make the eventual transition to
 `setuptools`_ as painless as possible.
 
 Because we will be using `distutils`_, there will be no method for
 automatically installing dependencies.  Instead, we are following the approach
 of `Matplotlib`_ which can be summarized as follows:
 
 - Distinguish between required and optional dependencies.  However, the required
   dependencies for IPython should be only the Python standard library.
   
 - Upon installation check to see which optional dependencies are present and
   tell the user which parts of IPython need which optional dependencies.
 
 It is absolutely critical that each subpackage of IPython has a clearly
 specified set of dependencies and that dependencies are not carelessly
 inherited from other IPython subpackages. Furthermore, tests that have certain
 dependencies should not fail if those dependencies are not present. Instead
 they should be skipped and print a message.
 
 .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
 .. _distutils: http://docs.python.org/lib/module-distutils.html
 .. _Matplotlib: http://matplotlib.sourceforge.net/
 
 Specific subpackages
 --------------------
 
 ``core``
     This is the core functionality of IPython that is independent of the
     terminal, network and GUIs.  Most of the code that is in the current
     IPython trunk will be refactored, cleaned up and moved here.
 
 ``kernel``
     The enables the IPython core to be expose to a the network.  This is
     also where all of the parallel computing capabilities are to be found.
     
 ``config``
     The configuration package used by IPython.
 
 ``frontends``
     The various frontends for IPython.  A frontend is the end-user application
     that exposes the capabilities of IPython to the user.  The most basic
     frontend will simply be a terminal based application that looks just like
     today 's IPython.  Other frontends will likely be more powerful and based
     on GUI toolkits.
 
 ``notebook``
     An application that allows users to work with IPython notebooks.
 
 ``tools``
     This is where general utilities go.
 
 
 Version control
 ===============
 
 In the past, IPython development has been done using `Subversion`__.  Recently,
 we made the transition to using `Bazaar`__ and `Launchpad`__.  This makes it
 much easier for people to contribute code to IPython.  Here is a sketch of how
 to use Bazaar for IPython development.  First, you should install Bazaar.
 After you have done that, make sure that it is working by getting the latest
 main branch of IPython::
 
     $ bzr branch lp:ipython
 
 Now you can create a new branch for you to do your work in::
 
     $ bzr branch ipython ipython-mybranch
 
 The typical work cycle in this branch will be to make changes in
 ``ipython-mybranch`` and then commit those changes using the commit command::
 
     $ ...do work in ipython-mybranch...
     $ bzr ci -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!
 
 If we couple this with a policy of making single commits for each reasonably
 atomic change, the bzr log should give an excellent view of the project, and
 the `--short` log option becomes a nice summary.
 
 While working with this branch, it is a good idea to merge in changes that have
 been made upstream in the parent branch.  This can be done by doing::
 
     $ bzr pull
     
 If this command shows that the branches have diverged, then you should do a
 merge instead::
 
     $ bzr merge lp:ipython
 
 If you want others to be able to see your branch, you can create an account
 with launchpad and push the branch to your own workspace::
 
     $ bzr push bzr+ssh://<me>@bazaar.launchpad.net/~<me>/+junk/ipython-mybranch
 
 Finally, once the work in your branch is done, you can merge your changes back
 into the `ipython` branch by using merge::
 
     $ cd ipython
     $ merge ../ipython-mybranch
     [resolve any conflicts]
     $ bzr ci -m "Fixing that bug"
     $ bzr push
 
 But this will require you to have write permissions to the `ipython` branch.
 It you don't you can tell one of the IPython devs about your branch and they
 can do the merge for you.
 
 More information about Bazaar workflows can be found `here`__.
 
 .. __: http://subversion.tigris.org/
 .. __: http://bazaar-vcs.org/
 .. __: http://www.launchpad.net/ipython
 .. __: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html
 
 Documentation
 =============
 
 Standalone documentation
 ------------------------
 
 All standalone documentation should be written in plain text (``.txt``) files
 using `reStructuredText`_ for markup and formatting. All such documentation
 should be placed in the top level directory ``docs`` of the IPython source
 tree. Or, when appropriate, a suitably named subdirectory should be used. The
 documentation in this location will serve as the main source for IPython
 documentation and all existing documentation should be converted to this
 format.
 
 In the future, the text files in the ``docs`` directory will be used to
 generate all forms of documentation for IPython. This include documentation on
 the IPython website as well as *pdf* documentation.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
 Docstring format
 ----------------
 
 Good docstrings are very important. All new code will use `Epydoc`_ for
 generating API docs, so we will follow the `Epydoc`_ conventions. More
 specifically, we will use `reStructuredText`_ for markup and formatting, since
 it is understood by a wide variety of tools. This means that if in the future
 we have any reason to change from `Epydoc`_ to something else, we'll have fewer
 transition pains.
 
 Details about using `reStructuredText`_ for docstrings can be found `here
 <http://epydoc.sourceforge.net/manual-othermarkup.html>`_.
 
 .. _Epydoc: http://epydoc.sourceforge.net/
 
 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 
   similar interfaces and for interfaces that are similar.
 
 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.
 
 This may be confusing as most of the existing IPython codebase uses a different
 convention (``lowerCamelCase`` for methods and attributes).  Slowly, we will
 move IPython over to the new convention, providing shadow names for backward
 compatibility in public interfaces.
 
 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`_
 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.
 
 .. _Nose: http://code.google.com/p/python-nose/
 
 Tests of `Twisted`__ using code should be written by subclassing the
 ``TestCase`` class that comes with ``twisted.trial.unittest``. When this is
 done, `Nose`_ will be able to run the tests and the twisted reactor will be
 handled correctly.
 
 .. __: http://www.twistedmatrix.com
 
 Each subpackage in IPython should have its own ``tests`` directory that
 contains all of the tests for that subpackage. This allows each subpackage to
 be self-contained. 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 also need to look into use Noses ability to tag tests to allow a more
 modular approach of running tests.
 
 .. _devel_config:
 
 Configuration system
 ====================
 
 IPython uses `.ini`_ files for configuration purposes. This represents a huge
 improvement over the configuration system used in IPython. IPython works with
 these files using the `ConfigObj`_ package, which IPython includes as
 ``ipython1/external/configobj.py``.
 
 Currently, we are using raw `ConfigObj`_ objects themselves. Each subpackage of
 IPython should contain a ``config`` subdirectory that contains all of the
 configuration information for the subpackage. To see how configuration
 information is defined (along with defaults) see at the examples in
 ``ipython1/kernel/config`` and ``ipython1/core/config``. Likewise, to see how
 the configuration information is used, see examples in
 ``ipython1/kernel/scripts/ipengine.py``.
 
 Eventually, we will add a new layer on top of the raw `ConfigObj`_ objects. We
 are calling this new layer, ``tconfig``, as it will use a `Traits`_-like
 validation model.  We won't actually use `Traits`_, but will implement
 something similar in pure Python.  But, even in this new system, we will still
 use `ConfigObj`_ and `.ini`_ files underneath the hood. Talk to Fernando if you
 are interested in working on this part of IPython. The current prototype of
 ``tconfig`` is located in the IPython sandbox.
 
 .. _.ini: http://docs.python.org/lib/module-ConfigParser.html
 .. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html
 .. _Traits: http://code.enthought.com/traits/
 
+
 Installation and testing scenarios
 ==================================
 
 This section outlines the various scenarios that we need to test before we
 release an IPython version.  These scenarios represent different ways of
 installing IPython and its dependencies.
 
 Installation scenarios under Linux and OS X
 -------------------------------------------
 
     1.  Install from tarball using ``python setup.py install``.
         a.  With only readline+nose dependencies installed.
         b.  With all dependencies installed (readline, zope.interface, Twisted,
         foolscap, Sphinx, nose, pyOpenSSL).
 	    
     2.  Install using easy_install.
 
         a.  With only readline+nose dependencies installed.
             i.  Default dependencies: ``easy_install ipython-0.9.beta3-py2.5.egg``
             ii. Optional dependency sets: ``easy_install -f ipython-0.9.beta3-py2.5.egg IPython[kernel,doc,test,security]``
 
         b.  With all dependencies already installed.
 	
 
 Installation scenarios under Win32
 ----------------------------------
 
 	1.  Install everything from .exe installers
 	2.  easy_install?
 
 
 Tests to run for these scenarios
 --------------------------------
 
     1.  Run the full test suite.
     2.  Start a controller and engines and try a few things by hand.
         a.  Using ipcluster.
         b.  Using ipcontroller/ipengine by hand.
 
     3.  Run a few of the parallel examples.
     4.  Try the kernel with and without security with and without PyOpenSSL
         installed.
     5.  Beat on the IPython terminal a bunch.
     6.  Make sure that furl files are being put in proper locations.
+
+
+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.
+
+#. 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!

docs/source/index.txt

@@ -1,32 +1,32 b''
 =====================
 IPython Documentation
 =====================
 
 .. htmlonly::
 
-   :Release: |version|
+   :Release: |release|
    :Date: |today|
 
    Contents:
 
 .. toctree::
    :maxdepth: 2
 
    overview.txt
    install/index.txt
    interactive/index.txt
    parallel/index.txt
    config/index.txt
    changes.txt
    development/index.txt
    faq.txt
    history.txt
    license_and_copyright.txt
    credits.txt
 
 
 .. htmlonly::
 
   * :ref:`genindex`
   * :ref:`modindex`
   * :ref:`search`