[IPython-dev] ChangLog vs changes.txt

Brian Granger ellisonbg.net@gmail....
Thu Jun 12 15:45:37 CDT 2008


On Thu, Jun 12, 2008 at 2:41 PM, Fernando Perez <fperez.net@gmail.com> wrote:
> On Thu, Jun 12, 2008 at 11:36 AM, Brian Granger <ellisonbg.net@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.

Great!

Brian

>
> Cheers,
>
> f
>


More information about the IPython-dev mailing list