[39023] trunk/base

[Ryan Schmidt]

On Aug 6, 2008, at 03:48, Anders F Björklund wrote:

> Ryan Schmidt wrote:
>
>>> Hmm, I thought ChangeLog was in chronological order (which you
>>> just broke) ?
>>
>> Since the ChangeLog is something the casual user might be expected
>> to read, it should be concise and organized.
>>
>> The Subversion log is in chronological order. The ChangeLog should
>> not merely duplicate the Subversion log. Rather, it should have one
>> entry per logical change.
>>
>> I would also say that the most important changes should be first in
>> the ChangeLog, so that a user who begins to read it but gives up
>> before reaching the end learns the most important things anyway.
>>
>> Such rearrangement and consolidation of the ChangeLog is probably
>> something the release manager should do right before a release. I'm
>> just trying to get a head start.
>
> A matter of conventions, I suppose. I normally have "NEWS" as the
> user-readable, and ChangeLog for development.
>
> The version control log is more like "end of day commit, fix typo,
> oops move that function, missed a file" etc.

Hmm. Indeed, we do have a NEWS file with a much more concise summary  
of changes.

So what is the ChangeLog good for then, since anyone interested in  
detailed changes can consult the Subversion log? I seem to remember a  
discussion about this before... Let's see...


James Berry reminds us that we need to update the ChangeLog when we  
make changes to base:

http://lists.macosforge.org/pipermail/macports-dev/2007-April/ 
001324.html


Randall Wood asks why the ChangeLog can't be generated automatically  
from the Subversion log. Juan Manuel Palacios says the ChangeLog  
should summarize commit messages, not duplicate them, and that it's  
acceptable to group multiple commits or tickets into a single  
ChangeLog entry. (I would increase "acceptable" to "desirable".)

http://lists.macosforge.org/pipermail/macports-dev/2007-December/ 
003689.html


In this question I asked about the ChangeLog, right before 1.6.0's  
release, Juan Manuel mentioned having recently created the NEWS file.  
I guess it would then be the release manager's job to create the NEWS  
file, and to do so he would draw on what's in the ChangeLog file.

http://lists.macosforge.org/pipermail/macports-dev/2007-December/ 
003749.html