ChangeLog policy (Re: r12219 - gnucash/trunk/src - Move functions from GncPluginPageAccountTree to GncTreeViewAccount)

[Chris Shoemaker]

On Sat, Dec 31, 2005 at 12:45:42PM +0100, Christian Stimming wrote:
> Hi Chris,
> 
> thanks for this nice work. It's certainly good if common functionality can be 
> moved to a place where it belongs even better.
> 
> However, I would kindly like to ask that you stick to gnucash's so-far 
> convention and add some entry to the ChangeLog file -- especially for stuff 
> like "move functions xy from file a to file b", and especially when there's a 
> recent ChangeLog entry that talks about precisely those functions xy. 
> (hampton on 2005-12-29: "src/gnome/gnc-plugin-page-account-tree.c ...:  
> Migrate the account page options to a new "Filter By" dialog. " -- I tried to 
> double-check some translations and was rather surprised/annoyed not to find 
> any of those functions in that file or directory anymore.) 
> 
> We all know that you've proposed a different approach to ChangeLog handling 
> and this has been discussed before, but there was no final conclusion and/or 
> consensus about a new policy. Therefore I would kindly ask that we do 
> continue the old policy as long as we don't have agreed on a new one. And 
> "moving stuff from file a to file b" is certainly that kind of ChangeLog 
> notes that should be collected in a central file, because that's where 
> developers look up the latest changes (or at least that's what I used to do 
> and would like to do in the future). 
> 
> And no, from looking at http://svn.gnucash.org/trac/timeline I cannot 
> immediately see that hampton's "new Filter-By dialog" is now no longer in 
> gnc-plugin-page-account-tree.c but in a different file instead. Even if I run 
> "make ChangeLog.svn" then the (to me) important information "stuff was moved 
> from file a to file b" is lost in all kinds of minor tweaks here and there. 
> IMHO when looking at ChangeLog.svn about 10% of the actual commits affect 
> other developers in a way that should be documented, and the rest of the 
> commits don't and don't need to be documented more than the SVN commit 
> message. The process of manually adding an entry to the ChangeLog file IMHO 
> precisely offers this filtering step, so that "ChangeLog" is basically 
> "ChangeLog.svn minus noise". That's why I still stick with the previous 
> ChangeLog policy of gnucash.
> 
> Christian
> 

Christian,

First, I'm sorry about neglecting the ChangeLog.  I'll add some
ChangeLog entries.

Second, I agree that it's superficially appealing to put only
"important" changed in the ChangeLog, but I have to disagree about the
feasibility of selecting some small subset of commits which to include
in the ChangeLog.  The problem is that different commits (and numbers
of commits) will be important to different developers and no
reasonable heuristic exists for predicting which commits will be
important.  The only solution is to make a good ChangeLog entry for
*every* commit, and to make it easy to search the ChangeLog for what's
important to you at the moment.

That said, determining how to efficiently maintain that log, is more
of a technical issue.  I know that the trac timeline is seriously
deficient in not having the affected paths listed.  And, I know that
me just abandoning "ChangeLog" when that's where developers expect to
look is also not good.

I also know that ChangeLog.svn has some deficiencies, like completely
ruining whitespace and UTF8.  Fortunately, those are just deficiencies
in the script, since SVN actually saves a good log.

I think that a generated ChangeLog is no (or not much) better nor
worse than a rigorously maintained ChangeLog in terms of utility.
(It's benefit is only efficiency.)  The only way to improve utility is
to write better messages or use better archeology tools.
Incidentally, there are some amazingly useful examples of this
floating around.  The things you can do with combinations of
git-{whatchanged,log,shortlog,diff} are astounding.

So, I'll update ChangeLog until I convince the world to end the
duplication, but as for identifying what changes impact you, we'll
just have to keep the messages good and use good search tools.

-chris