[RFC] Policy change for ChangeLog

[Derek Atkins]

Neil Williams <linux at codehelp.co.uk> writes:

> On Friday 02 December 2005 9:32 pm, Chris Shoemaker wrote:
>> > All you get is the overarching description.  You lose the ability to
>> > say what happened in each file.  Maybe you don't document your
>> > changes enough to want that ability, but I do.
>>
>> Per-file documentation of a single commit is fine.  Documenting the
>> same commit in two different places (potentially inconsistently) is
>> the problem.
>
> David's last commit is a case in point. Just what is the benefit of the 
> ChangeLog entry compared to the email to gnucash-changes?

Email is empheral, and it's not distributed with the tarball.
The ChangeLog is saved and is part of the tarball.  The benefit
is distributed a log of the changes in the tarball, which /is/
the end goal.

[snip]

> That is just bloat. No?

I don't consider it bloat.

> That's no disrespect to you, David, just an illustration of the duplication 
> inherent in the current methods.

Um, no, that's not the duplication that Chris is complaining about.
He's not complaining about the gnucash-changes email -- he's
complaining about the work required to actually modify the changelog
and then cut-and-paste that into the commit log.

> Can we exempt ChangeLog from the gnucash-changes content?
> (Looking at the duplication from the other direction.)

I don't think so.  You're welcome to look at the email hook and
suggest a patch...  But I really don't see why.  IMHO working on that
is just a waste of your time.

> OK. My process, not using emacs:
>
> 1. Ask svn status what has been changed and make sure any svn move operations 
> show up (!)
> 2. Direct svn diff to a file and inspect.
> 3. Copy svn status output into the ChangeLog using vi.
> 4. Edit the ChangeLog to describe each part of the upcoming commit.
> (no network access yet)
> 5. Make the commit using -m to add a short commit message.
>
> I'd like the *option* to skip stages 3 and 4 if the changes are repetitively 
> making the same changes to multiple files or unrelated to the final 
> distributed code.

I /do/ think it's reasonable for a repetative commit to eliminate
the list of files changed from the ChangeLog.  However you should
still make a ChangeLog entry.  E.g.:

   1000-13-32    Joe Q. Developer <gnucash at dev.example>

          * corrected the FSF address in every source file

IMHO a ChangeLog entry like this is /perfectly reasonable/.

> I think this is particularly important for Doxygen fixes.
>
> I cannot see how maintainers benefit from all the bloat arising from 
> documenting all the Doxygen tweaks in ChangeLog.

It gives a history of when a file was changed and how.

> Can we recommend that ChangeLog is only for CODE changes and that changes to 
> comments, AUTHORS, README, Doxygen, things like the FSF address change and 
> housekeeping tasks like removing unwanted headers are simply not put into 
> ChangeLog at all? 

Nah.  I'd like a log of all changes, please.

> Basically, keep ChangeLog for changes that actually change the compiled 
> binaries or build system?

Why?  Is it really that much /work/ to create a ChangeLog entry?
The 'bloat' as you call it is unimportant.  Size can be handled
fine.  We have plenty of space.  Disk is cheap.

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available