[RFC] Policy change for ChangeLog

Chris Shoemaker c.shoemaker at cox.net
Thu Dec 1 16:25:45 EST 2005


Developers,

        I'm requesting comments on the following policy change.  I
believe this change would streamline GnuCash development.

* Background

        For many years now, the development policy has included a
requirement to make an entry in the ChangeLog file describing the
changes made and, ideally, listing the files changed.  This
information is often quite useful to developers trying to understand
the current code state.  CVS did not provide any easy way of
reconstructing this information, so the ChangeLog file was necessary.

* Problem

        GnuCash has moved from CVS to Subversion (SVN).  SVN does
natively provide a mechanism for viewing the information that was
intended to be stored in the ChangeLog file.  For example,

$ svn log -v
------------------------------------------------------------------------
r12076 | hampton | 2005-11-30 20:45:24 -0500 (Wed, 30 Nov 2005) | 2 lines
Changed paths:
   M /gnucash/trunk/ChangeLog
   M /gnucash/trunk/src/business/business-gnome/dialog-date-close.c
   M /gnucash/trunk/src/gnome/dialog-sxsincelast.c
   M /gnucash/trunk/src/gnome/dialog-tax-info.c
   M /gnucash/trunk/src/gnome/window-reconcile.c
   M /gnucash/trunk/src/gnome-search/dialog-search.c
   M /gnucash/trunk/src/gnome-search/search-account.c
   M /gnucash/trunk/src/gnome-utils/dialog-options.c
   M /gnucash/trunk/src/gnome-utils/gnc-date-edit.c
   M /gnucash/trunk/src/gnome-utils/gnc-html-graph-gog.c
   M /gnucash/trunk/src/register/register-gnome/gnucash-header.c

Eliminate the deprecated function gtk_widget_set_usize().

------------------------------------------------------------------------
r12075 | hampton | 2005-11-30 20:14:03 -0500 (Wed, 30 Nov 2005) | 3 lines
Changed paths:
   M /gnucash/trunk/ChangeLog
   M /gnucash/trunk/src/business/business-gnome/search-owner.c
   M /gnucash/trunk/src/gnome/gnc-split-reg.c
   M /gnucash/trunk/src/gnome-utils/gnc-query-list.c
   M /gnucash/trunk/src/register/register-gnome/gnucash-date-picker.c

Finish converting type creation over from gtk_type_unique() to
g_type_register_static().
.
.
.

Compare:

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

        * src/register/register-gnome/gnucash-date-picker.c:
        * src/business/business-gnome/search-owner.c:
        * src/gnome-utils/gnc-query-list.c:
        * src/gnome/gnc-split-reg.c: Finish converting type creation over
        from gtk_type_unique() to g_type_register_static().

        * various: More trivial conversions from deprecated gtk/gnome
        functions to supported functions.
.
.
.

        This new feature affords us the opportunity to increase
development efficiency.

        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.
        - Having two commit descriptions and two affected-path lists
increases the chance for inconsistency.
        - It is quite inconvenient to reflect/detect in the ChangeLog
which branch is affected by a change.
        - It is tedious to manually compose the affected path list.

* Solutions

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

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

        I think this proposed practice would,
        - reduce the time spent composing commit messages, 
        - eliminate time spent composing affected path list,
        - encourage more helpful commit messages,
        - consolidate redundant information,
        - provide a more accurate commit history.

Comments?

-chris


More information about the gnucash-devel mailing list