[IPython-dev] ChangLog vs changes.txt

Brian Granger ellisonbg.net@gmail....
Thu Jun 12 13:36:50 CDT 2008


Hi,

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
following reasons:

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:

docs/source/changes.txt

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:


########################## changes.txt

.. _changes:

==========
What's new
==========

.. contents::

Release 0.9
===========

New features
------------

	* 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.

Bug fixes
---------

	* A few subpackages has missing `__init__.py` files.
	* The documentation is only created is Sphinx is found.  Previously,
the `setup.py`
	  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
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
=============

Someone needs to describe what went into 0.8.4.

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.

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.

Older releases
==============

Changes in earlier releases of IPython are described in the older file
``ChangeLog``.
Please refer to this document for details.

########################## /changes.txt

So, what do people think about this proposal?

Cheers,

Brian


More information about the IPython-dev mailing list