[IPython-dev] ChangLog vs changes.txt
ellisonbg.net at gmail.com
Thu Jun 12 14:36:50 EDT 2008
In the process of reorganizing the IPython documentation, I ran into
something related to the ChangeLog. In the past, IPython has used a
traditional ChangeLog for devs to record the changes they have made to
the project. This was used to keep track of who has done what and
what things have been done since the last release. In IPython1 on the
other hand, I had moved away from using the ChangeLog for the
1. A linear ChangeLog is a poor reflection of what happens to the
core when a distributed VCS is used. In fact, I would say it could
potentially be downright confusing.
2. The ChangeLog really is a repetition of the information that is
contained in the commit messages (which in a DVCS do reflect the
distributed/parallel nature of development).
3. The ChangeLog doesn't really give users anything useful. Sure
they could read it, but it is not written in a user focused manner and
they would have to sift through a lot of irrelevant information.
4. To generate things like release notes, what's new, api changes
etc. (user focused docs), someone has to do the tedious task of
looking through the ChangeLog and summarizing the changes in user
friendly form. The success of this is shown in the lack of user
focued high quality release notes, what new and api change
documentation for IPython.
5. For those of us who don't use emacs, the format of the ChangeLog
leaves something to be desired.
6. The ChangeLog format does not integrate with our Sphinx docs as it
is not rst.
To address these issue with IPython1, we recently went the following route:
1. We no longer maintain a ChangeLog
2. We instead have a changes.txt files that is 1) regular rst and 2)
part of our Sphinx based docs.
This document lists changes for each release of IPython separately and
for each release, includes three sections: new features, bug fixes and
backward incompatible changes. The goal of this document is to record
in a user focused way all of the changes to IPython. I was inspired
to create this after looking at how a number of different projects
handle this issue.
So, for now I have left the IPython ChangeLog in place, but I propose
that we abandon it (move it to docs/attic) and begin using the new
document that I have created:
At some level, I picture this file as part of our contract with users.
If there is something new that a user needs to know about IPython,
this is where they should look. Also note that the file immediately
provides a usable release notes for our releases.
Here is what that document looks like currently, to give you an idea:
* 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
* We have switched to using Foolscap for all of our network protocols in
:mod:`IPython.kernel`. This gives us secure connections that are
* 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
what this means in this file. All developer should read this and use the new
banner in all IPython source code files.
* A few subpackages has missing `__init__.py` files.
* The documentation is only created is Sphinx is found. Previously,
script would fail if it was missing.
Backwards incompatible changes
* 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
and the constructor can be left empty.
* The asynchronous clients in :mod:`IPython.kernel.asyncclient` are
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
If you were using custom config files before, you should delete
them and regenerate
Changes merged in from IPython1
* Much improved ``setup.py`` and ``setupegg.py`` scripts. Because Twisted
and zope.interface are now easy installable, we can declare them as
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
* Functions can now be pushed/pulled to/from engines using
* 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
* New developer oriented documentation: development guidelines and roadmap.
* Traditional ``ChangeLog`` has been changed to a more useful
that is organized by release and is meant to provide something more relevant
* 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
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
These things are now handled with the ``targets`` keyword argument
* The :attr:`MultiEngineClient.magicTargets` has been renamed to
* All methods in the MultiEngine interface now accept the optional
* 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
that wraps the user's exceptions, rather than just raising the raw
* Changed the ``setupNS`` and ``resultNames`` in the ``Task`` class
Someone needs to describe what went into 0.8.4.
* %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.
* 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.
Changes in earlier releases of IPython are described in the older file
Please refer to this document for details.
So, what do people think about this proposal?
More information about the IPython-dev