[IPython-dev] ChangLog vs changes.txt

[Fernando Perez]

On Thu, Jun 12, 2008 at 11:36 AM, Brian Granger <ellisonbg.net at gmail.com> wrote:
> 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.


Yup, when I did the big bzr merge I mentioned that the old-style
changelog was likely the only file that would probably cause recurrent
merge conflicts if we tried to use it, so it would be best to stop
now.  Ville concurred, if I recall correctly.

One comment on this: with SVN, we were used to very terse commit
messages and the more detailed info in the changelog.  I'd like to
encourage everyone now to do the following, since the commit log will
be *the* history: use a docstring-like approach in the commit
messages:

"""Single line summary of  changes being committed.
# BLANK LINE
- 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.

I've added this to the rst dev guidelines now.


Cheers,

f