[IPython-dev] ChangLog vs changes.txt
Thu Jun 12 15:45:37 CDT 2008
On Thu, Jun 12, 2008 at 2:41 PM, Fernando Perez <email@example.com> wrote:
> On Thu, Jun 12, 2008 at 11:36 AM, Brian Granger <firstname.lastname@example.org> wrote:
>> 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:
>> 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
> """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.
More information about the IPython-dev