[RFC] Policy change for ChangeLog

[Neil Williams]

On Thursday 01 December 2005 9:25 pm, Chris Shoemaker wrote:
>         The problems with continuing to use the existing ChangeLog
> policy are:
>         - Having to write two commit descriptions increases the chance
> that both will be of lesser quality than if only one description was
> required.

To me, the biggest problem is just the sheer size of the ChangeLog files, 
despite the split. That and the constant presence of ChangeLog in every svn 
update.

>         - It is quite inconvenient to reflect/detect in the ChangeLog
> which branch is affected by a change.

Absolutely.

>         - It is tedious to manually compose the affected path list.

(I did post a script that solved that problem directly from svn status but it 
is still duplication.)

>         Since,
>         - the ChangeLog and SVN log currently duplicate information,
>         - the svn affected paths list is automatic and provably correct,
>         - svn affected paths list clearly indicate affected branch,
>
>         I propose that we,
>         - discontinue the practice of manually placing commit logs
> into the ChangeLog file,

Seconded. (!)

>         - instead use the ChangeLog for "big picture" descriptions of
> code developments, such as changes in features, code re-organization,
> architectural changes, build system changes, branch/merge operations,
> etc.

Is it really suitable for that? Such descriptions may need a free format text 
file (as with GNOME2_STATUS) or may be best done in Doxygen. A ChangeLog has 
quite a formal and restrictive syntax (which is why branches don't fit well).

>         Alternatively, we could place "big picture" descriptions
> somewhere else.  I envision that the "big picture" descriptions would
> be much closer to a suitable "release log" at release time than the
> current ChangeLog is.

In other words, one or two line summaries of the biggest changes.

>         Optionally, if we desire to maintain a SVN-independent
> file-format of commit history, I propose we automate that archival,
> e.g. 'svn -v -r BASE >> CommitLog'

Alternatively, the script could use the current svn messages and create the 
logs for us - after all, the server running the script knows the name and 
email address of the developer making the commit and it knows the time. svn 
provides the rest.

All in all, the gnucash-changes mailing list archive provides quite an 
expansive changelog. I'd like to do away with ChangeLog for interim/routine 
commits and consider it a "public" file that will form the basis of the 
release notes. Something that is changed only as often as files like AUTHORS 
and README.

-- 

Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20051201/ac753e6d/attachment.bin