[RFC] Policy change for ChangeLog

[Neil Williams]

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?

Modified:
   gnucash/trunk/ChangeLog
   gnucash/trunk/src/business/business-gnome/dialog-date-close.c
   gnucash/trunk/src/gnome-search/dialog-search.c
   gnucash/trunk/src/gnome-search/search-account.c
   gnucash/trunk/src/gnome-utils/dialog-options.c
   gnucash/trunk/src/gnome-utils/gnc-date-edit.c
   gnucash/trunk/src/gnome-utils/gnc-html-graph-gog.c
   gnucash/trunk/src/gnome/dialog-sxsincelast.c
   gnucash/trunk/src/gnome/dialog-tax-info.c
   gnucash/trunk/src/gnome/window-reconcile.c
   gnucash/trunk/src/register/register-gnome/gnucash-header.c
Log:
Eliminate the deprecated function gtk_widget_set_usize().


Modified: gnucash/trunk/ChangeLog
===================================================================
--- gnucash/trunk/ChangeLog     2005-12-01 01:14:03 UTC (rev 12075)
+++ gnucash/trunk/ChangeLog     2005-12-01 01:45:24 UTC (rev 12076)
@@ -1,5 +1,17 @@
 2005-11-30  David Hampton  <hampton at employees.org>
 
+       * src/register/register-gnome/gnucash-header.c:
+       * src/business/business-gnome/dialog-date-close.c:
+       * src/gnome-utils/gnc-date-edit.c:
+       * src/gnome-utils/gnc-html-graph-gog.c:
+       * src/gnome-utils/dialog-options.c:
+       * src/gnome/window-reconcile.c:
+       * src/gnome/dialog-sxsincelast.c:
+       * src/gnome/dialog-tax-info.c:
+       * src/gnome-search/search-account.c:
+       * src/gnome-search/dialog-search.c: Eliminate the deprecated
+       function gtk_widget_set_usize().

That is just bloat. No?

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

If we want this info in the ChangeLog for those who work on the distribution 
tarball, then do we need the ChangeLog diff sent to the gnucash-changes 
mailing list?

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

> Ok, yeah, that's pretty much the process I envisioned.  When you write
> it out like that it seems even more circular.  Svn knows what files we
> changed, so we:
>   1) ask it what we changed,
>   2) cut-n-paste file list into ChangeLog,
>   3) describe our commit,
>   4) cut-n-paste back into svn when it asks why we're
> changing the files.
>
> I'm sure I'll be glad when I can skip 1, 2 and 4.  And for the poor
> souls who aren't using emacs... :(

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 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.

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? 

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

-- 

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/20051202/e10c5522/attachment.bin