[RFC] Policy change for ChangeLog

classic Classic list List threaded Threaded
33 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[RFC] Policy change for ChangeLog

Chris Shoemaker
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  <[hidden email]>

        * 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
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Neil Williams-2
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/


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

attachment0 (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Josh Sled
In reply to this post by Chris Shoemaker
On Thu, 2005-12-01 at 16:25 -0500, Chris Shoemaker wrote:
> Comments?

This change is fine with me, and sounds good.

...jsled
--
http://asynchronous.org/ - `a=jsled; b=asynchronous.org; echo ${a}@${b}`
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
Quoting Josh Sled <[hidden email]>:

> On Thu, 2005-12-01 at 16:25 -0500, Chris Shoemaker wrote:
>> Comments?
>
> This change is fine with me, and sounds good.

Before we go ahead with this, I'd like to hear from Chris Lyttle
and Christian Stimming..  They're the ones who usually use the
ChangeLog to generate the NEWS and release notes.  I'd like to
hear if they are willing to accept the new process going forward.

At some level it's OUR job as developers to make OTHERS lives
easier..  While we should certainly use tools to make OUR lives
easier, we need to think of who is using what we create and how
they use it.  Making life easier for us at their expense is NOT
okay.  So, I'd like to hear from wilddev and cstim first.

Personally, I like being able to grep through the changelog in order
to see, e.g. whether a particular change made it into a particular
release.  I suppose I can always redirect the log/status command into
a file and grep it there.

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Thomas Bushnell BSG
In reply to this post by Chris Shoemaker
Chris Shoemaker <[hidden email]> writes:

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

Write one description, and commit it to two places.

PLEASE continue to conform to the GNU Coding Standards; there are
important reasons for them.

You have, it seems to me, entirely ignored the value of the ChangeLog
to everyone who examines the sources distributed in the tarballs.

If you want to automatically generate the ChangeLog, which continues
to carry all the same information, that's great.  I don't care *how*
the ChangeLog file gets into the distribution, only that it do so.

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

The GNU Coding Standards already have a place for "big picture"
descriptions; they belong in the NEWS file.

Thomas
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Thomas Bushnell BSG
In reply to this post by Derek Atkins
Derek Atkins <[hidden email]> writes:

> Personally, I like being able to grep through the changelog in order
> to see, e.g. whether a particular change made it into a particular
> release.  I suppose I can always redirect the log/status command into
> a file and grep it there.

People who must use and manipulate the sources after they have been
distributed definitely want ChangeLogs.

Also, I would note that a ChangeLog satisfies the GPL's
modification-notice requirement, and an undistributed svn log does
not.

Thomas

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Thomas Bushnell BSG
Thomas Bushnell BSG <[hidden email]> writes:

> If you want to automatically generate the ChangeLog, which continues
> to carry all the same information, that's great.  I don't care *how*
> the ChangeLog file gets into the distribution, only that it do so.

Another option would be to perform a "svn2cl" during "make dist"
and add the ChangeLog to the EXTRA_DIST target.

  http://ch.tudelft.nl/~arthur/svn2cl/

I don't particularly like this option, but it's something to
consider.

-derek
--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Christian Stimming
In reply to this post by Derek Atkins
Derek Atkins schrieb:

>> On Thu, 2005-12-01 at 16:25 -0500, Chris Shoemaker wrote:
>>
>>> Comments?
>>
>> This change is fine with me, and sounds good.
>
> Before we go ahead with this, I'd like to hear from Chris Lyttle
> and Christian Stimming..  They're the ones who usually use the
> ChangeLog to generate the NEWS and release notes.  I'd like to
> hear if they are willing to accept the new process going forward.

I wouldn't throw away our ChangeLog convention too quickly. It used to
be (and still is) a good compromise between readability and verbosity.

The problem is that we don't have any experience with maintaining that
obnoxious "big picture file", which supposedly would be the NEWS file.
So far that file has been used for the release notes until 1.7.8 but is
unused since them. We do have experience with the Changelog file, and
these are good experiences so far. Developer tend to copy the ChangeLog
entry to the CVS/SVN commit log or vice versa, so this convention
doesn't seem to put too much of an additional work on the developers.

As for compiling the release notes: Definitely the "svn log" is way too
verbose for the normal release note compilation. Currently working
through anything between 100 or 500 lines of ChangeLog during 1.8.x was
doable, but thousands of lines of "svn log" really is way too much.

IMHO our ChangeLog convention or what developers did from that meant
that all the totally-trivial things were already filtered out, and this
would be lost if we don't use ChangeLog at all. The point is that
ChangeLog still is the "note collection for the developers", whereas the
NEWS is the "note collection for the public", i.e. only that stuff that
as the time of writing is already considered fundamentally important.
Many things that might not be considered important at the time of
writing will not be added to the NEWS file, whereas they are added to
the ChangeLog -- where the release note collectors will pick it up at
the time when it's required.

> At some level it's OUR job as developers to make OTHERS lives
> easier..  While we should certainly use tools to make OUR lives
> easier, we need to think of who is using what we create and how
> they use it.  Making life easier for us at their expense is NOT
> okay.  So, I'd like to hear from wilddev and cstim first.

I prefer if there still is a place where every developer adds a note for
the majority of the non-trivial commits. Doesn't have to be the
ChangeLog, but IMHO that's the easiest way to do this. The NEWS file
IMHO is "too official"/"too public" for that goal.

Christian
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Thomas Bushnell BSG
On Thu, Dec 01, 2005 at 06:05:45PM -0800, Thomas Bushnell BSG wrote:
> Derek Atkins <[hidden email]> writes:
>
> > Personally, I like being able to grep through the changelog in order
> > to see, e.g. whether a particular change made it into a particular
> > release.  I suppose I can always redirect the log/status command into
> > a file and grep it there.
>
> People who must use and manipulate the sources after they have been
> distributed definitely want ChangeLogs.

I agree with your conclusion.  I think we should distribute a
ChangeLog, but...

> Also, I would note that a ChangeLog satisfies the GPL's
> modification-notice requirement, and an undistributed svn log does
> not.

I don't think this little detail is correct.  A ChangeLog also does
not satisfy that requirement.  

GPL 2a) "You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change."

[obligatory IANAL] Thus, change notification must be carried by the
changed files themselves.  I realize that a ChangeLog does perform
most (but not all) of the *intended* requirement here, but that
doesn't make it a true satisfaction, and the GNU Coding Standards make
no such claim about ChangeLogs.

(If we only distributed a tarball, there might be *some* room to argue
that the modified files "carry" sufficient notice with them in other
files in the tarball, but that's a stretch IMO.)

It becomes very clear that the ChangeLog is insufficient when we
realize that the GPL must be followed in whatever GPL'd work we
*distribute*.  We are currently distributing the individual GPL'd
files via several public methods.  Yes, the individual files are GPL'd
works; they say so explicitly.

So are we following the GPL?  Yes.  When I creatively modify a GPL'd
file I will add "Copyright (C) 2005 Chris Shoemaker
<[hidden email]>" to the file.  This *does* legally satisfy GPL
2a, although it is far less useful than the corresponding ChangeLog
entry.

Therefore, we should distribute a ChangeLog, even though it does NOT
legally satisfy GPL 2a, because it is useful, and it does well
accomplish the intent of GPL 2a.  And, we should continue to include
notice of change in the changed files, because it DOES legally satisfy
GPL 2a, even though it doesn't well accomplish the intent of same.

There is clearly some room for improvement of the GPL here.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Christian Stimming
On Fri, Dec 02, 2005 at 03:45:35PM +0100, Christian Stimming wrote:

> Derek Atkins schrieb:
> >>On Thu, 2005-12-01 at 16:25 -0500, Chris Shoemaker wrote:
> >>
> >>>Comments?
> >>
> >>This change is fine with me, and sounds good.
> >
> >Before we go ahead with this, I'd like to hear from Chris Lyttle
> >and Christian Stimming..  They're the ones who usually use the
> >ChangeLog to generate the NEWS and release notes.  I'd like to
> >hear if they are willing to accept the new process going forward.
>
> I wouldn't throw away our ChangeLog convention too quickly. It used to
> be (and still is) a good compromise between readability and verbosity.
>
> The problem is that we don't have any experience with maintaining that
> obnoxious "big picture file", which supposedly would be the NEWS file.
> So far that file has been used for the release notes until 1.7.8 but is
> unused since them.

I think this is a shame.  We should have *somewhere* to collect
incremental "big picture" and "public-view" notes.  How about this: We
open an undated entry at the top of NEWS, to which we can
incrementally add content.  At release time, we bang the content into
release-log shape, possibly supplementing material from ChangeLog,
date it, version it, "close" it, and open a new empty, undated one for
the next release.

> We do have experience with the Changelog file, and
> these are good experiences so far. Developer tend to copy the ChangeLog
> entry to the CVS/SVN commit log or vice versa, so this convention
> doesn't seem to put too much of an additional work on the developers.
>
> As for compiling the release notes: Definitely the "svn log" is way too
> verbose for the normal release note compilation. Currently working
> through anything between 100 or 500 lines of ChangeLog during 1.8.x was
> doable, but thousands of lines of "svn log" really is way too much.

I agree that making release notes directly from the commit messages is
very difficult.  I think we should try to do it "as we go", and polish
it at release time.

BTW, you seem to expect that the ChangeLog is/would be significantly
smaller than "svn log", but I don't think it is, neither in practice
(just compare) nor in policy (from README.svn: "There must be a
ChangeLog entry for every commit. If you discover that you only
committed half the files you meant to and need to fix that up you do
not need a new ChangeLog entry.  But in general, ChangeLog entries are
mandatory. Changes with out ChangeLog entries will be reverted.")  So,
the same difficulty exists in both cases, but I think it can be
resolved by a better use of NEWS.

>
> IMHO our ChangeLog convention or what developers did from that meant
> that all the totally-trivial things were already filtered out, and this
> would be lost if we don't use ChangeLog at all. The point is that
> ChangeLog still is the "note collection for the developers", whereas the
> NEWS is the "note collection for the public", i.e. only that stuff that
> as the time of writing is already considered fundamentally important.
> Many things that might not be considered important at the time of
> writing will not be added to the NEWS file, whereas they are added to
> the ChangeLog -- where the release note collectors will pick it up at
> the time when it's required.
>
> >At some level it's OUR job as developers to make OTHERS lives
> >easier..  While we should certainly use tools to make OUR lives
> >easier, we need to think of who is using what we create and how
> >they use it.  Making life easier for us at their expense is NOT
> >okay.  So, I'd like to hear from wilddev and cstim first.
>
> I prefer if there still is a place where every developer adds a note for
> the majority of the non-trivial commits. Doesn't have to be the
> ChangeLog, but IMHO that's the easiest way to do this. The NEWS file
> IMHO is "too official"/"too public" for that goal.

I think developers should add a note for *every* commit (even trivial
ones).  We currently do this in the commit message.  We should also
somehow ensure that these messages are distributed with the source,
even when svn isn't used, and it makes sense that this be as a
ChangeLog.  Separately, we can accumulate "pre-release notes" at the
top of NEWS to ease burden of writing release notes.

What do you think?

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Derek Atkins
On Fri, Dec 02, 2005 at 09:04:45AM -0500, Derek Atkins wrote:

> Thomas Bushnell BSG <[hidden email]> writes:
>
> > If you want to automatically generate the ChangeLog, which continues
> > to carry all the same information, that's great.  I don't care *how*
> > the ChangeLog file gets into the distribution, only that it do so.
>
> Another option would be to perform a "svn2cl" during "make dist"
> and add the ChangeLog to the EXTRA_DIST target.
>
>   http://ch.tudelft.nl/~arthur/svn2cl/

Hmm, seems to be in the same vein as rcs2log and cvs2cl.  It's a bit
more complicated than I'd like, but I guess that's the price paid for
such precise control over formatting.

> I don't particularly like this option, but it's something to
> consider.

Is it more the concept of deriving ChangeLog at dist-time that you
don't like or this implementation using xsltproc?

I don't have any problem with the format of the raw output of svn -v
log as ChangeLog entries, but the existence of a program like svn2cl
implies that some people certainly do.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
Quoting Chris Shoemaker <[hidden email]>:

> Hmm, seems to be in the same vein as rcs2log and cvs2cl.  It's a bit
> more complicated than I'd like, but I guess that's the price paid for
> such precise control over formatting.

*shrugs*  I figured I'd throw it out.

>> I don't particularly like this option, but it's something to
>> consider.
>
> Is it more the concept of deriving ChangeLog at dist-time that you
> don't like or this implementation using xsltproc?

I don't like the concept of deriving the ChangeLog.  I see nothing
wrong with generating the ChangeLog by hand and then cut-and-paste
the log message into the commit-log.  It's what I've always done, and
as far as I can tell it's what everyone else does.  Create once, save
twice.

> I don't have any problem with the format of the raw output of svn -v
> log as ChangeLog entries, but the existence of a program like svn2cl
> implies that some people certainly do.

I think the raw output of "svn -v log" is rather ugly.
The again I don't see any problem with cut-and-paste.  Emacs
makes it just so easy as to be laughable.  I've spent more time
writing this email than it takes me to generate a log message
and save it to both the ChangeLog and the commit log.

> -chris

-derek
--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
On Fri, Dec 02, 2005 at 12:20:25PM -0500, Derek Atkins wrote:
> Quoting Chris Shoemaker <[hidden email]>:
>
> >Hmm, seems to be in the same vein as rcs2log and cvs2cl.  It's a bit
> >more complicated than I'd like, but I guess that's the price paid for
> >such precise control over formatting.
>
> *shrugs*  I figured I'd throw it out.

Well, I looked more closely at the xsl and I'm warming up to it.  It's
not nearly as complicated as I expected, and it does produce prettier
output.

>
> >>I don't particularly like this option, but it's something to
> >>consider.
> >
> >Is it more the concept of deriving ChangeLog at dist-time that you
> >don't like or this implementation using xsltproc?
>
> I don't like the concept of deriving the ChangeLog.  

Just an idea: What if there was a "make ChangeLog" target that
triggered on dist but could also be made by anybody who wanted a local
ChangeLog file?

> I see nothing
> wrong with generating the ChangeLog by hand and then cut-and-paste
> the log message into the commit-log.  It's what I've always done, and
> as far as I can tell it's what everyone else does.  Create once, save
> twice.

I don't know how to create the changed-path list without visting every
buffer I changed.  (or recall changing)  I've been using diffstat.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Derek Atkins
On Fri, Dec 02, 2005 at 09:04:45AM -0500, Derek Atkins wrote:
> Thomas Bushnell BSG <[hidden email]> writes:
>
> > If you want to automatically generate the ChangeLog, which continues
> > to carry all the same information, that's great.  I don't care *how*
> > the ChangeLog file gets into the distribution, only that it do so.
>
> Another option would be to perform a "svn2cl" during "make dist"
> and add the ChangeLog to the EXTRA_DIST target.

I googled for other options used by projects using svn.  I found:

 - some projects do something like
        `svn log --xml -v | xsltproc svn2cl.xsl - > ChangeLog`, or
        `svn log -v > ChangeLog`
   in a "make dist" target.
 - some projects just stoped using ChangeLog at cvs->svn migration and
tell the packager to manually run one of the above commands.

An advantage to using the "make dist" target is that there's
no chance of forgetting.  

My preferred implementation of the policy change is currently:

  - Continue the pattern Christian started of pulling old ChangeLog
entries into archive files.  These files would continue to live in svn.
  - The "newest" ChangeLog file would be a generated file, made during
"make dist", and "make ChangeLog".  It would be generated thusly:
    $ svn log -v --xml -r BASE:12076 | xsltproc \
        --stringparam strip-prefix "gnucash" --stringparam include-rev "yes" \
        ./svn2cl.xsl - > ./ChangeLog

  where 12076 is replaced once a period (e.g. annually) with the last
revision of the previous period.

  Therefore,
   - the ChangeLog(s) are distributed
   - local recent ChangeLog is available to anyone: "make ChangeLog"
   - maintenance of ChangeLogs is only periodic
   - no duplication of entries (except for archived ChangeLogs.200x)
   - no manual (or scripted, thanks Neil) creation of affected file paths.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
On Fri, Dec 02, 2005 at 02:14:30PM -0500, Chris Shoemaker wrote:
> My preferred implementation of the policy change is currently:
>
>   - Continue the pattern Christian started of pulling old ChangeLog
> entries into archive files.  These files would continue to live in svn.

BTW, I think that for every public release we should also archive the
ChangeLog at that time.  (That doesn't preclude also archiving for any
other occasion.)  It doesn't matter to me that the archive files are
named after years.  If we release version 2.1.1 on Oct. 2, 2006, then
the ChangeLog up to that release should move from "generated-land" to
"archive-land" (ChangeLog.2006) at the same time.

>   - The "newest" ChangeLog file would be a generated file, made during
> "make dist", and "make ChangeLog".  It would be generated thusly:
>     $ svn log -v --xml -r BASE:12076 | xsltproc \
>         --stringparam strip-prefix "gnucash" --stringparam include-rev "yes" \
>         ./svn2cl.xsl - > ./ChangeLog

I had to tweak this a bit to get all branches included.  My plan is to
commit something like this soon that actually generates ChangeLog.svn
(not ChangeLog).  Then, the next time we rotate the ChangeLog (either
for a release or for New Years), I want to archive the existing log
and make new entries "generated".  At that time, the generated file
will be called ChangeLog.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Chris Shoemaker
I just thought of the one reason this proposal really bothers me.
I knew there was something that wasn't sitting right and why I didn't
think this would work.  It's not that I'm against making developers
lives easier, but I want to make sure we don't lose something in kind.

I like the ability to specify what changed in each and every file.
Even when I commit a single feature, I like being able to specify
what I needed to change in each file to make that feature work.
I like being able to say:

   foo.c:  did this change
   bar.c:  did this other change
   quux.c: made yet another related change

And then have the overarching description:

   Made a bunch of changes to implement _foo_

When you leave the ChangeLog generation out of the developer's hands,
you can't get this level of detail.  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.

As for how to get the list of files changed, you can just run a diff:

  svn diff | grep '^Index'

Personally I feel you should always run an "svn diff | more" prior
to the commit to make sure you're only committing the change(s) you
want.  Note that unlike cvs, an svn diff does not touch the network.
Indeed, you could even create your ChangeLog entry as you're perusing
your svn diff prior to commit..  Then C-x C-s the ChangeLog buffer,
M-w to copy the changelog entry, and then C-y once you get the svn commit
log buffer.  Then just type what you want for the email subject in
the top line of the buffer and you're done.

-derek

Quoting Chris Shoemaker <[hidden email]>:

> On Fri, Dec 02, 2005 at 12:20:25PM -0500, Derek Atkins wrote:
>> Quoting Chris Shoemaker <[hidden email]>:
>>
>> >Hmm, seems to be in the same vein as rcs2log and cvs2cl.  It's a bit
>> >more complicated than I'd like, but I guess that's the price paid for
>> >such precise control over formatting.
>>
>> *shrugs*  I figured I'd throw it out.
>
> Well, I looked more closely at the xsl and I'm warming up to it.  It's
> not nearly as complicated as I expected, and it does produce prettier
> output.
>
>>
>> >>I don't particularly like this option, but it's something to
>> >>consider.
>> >
>> >Is it more the concept of deriving ChangeLog at dist-time that you
>> >don't like or this implementation using xsltproc?
>>
>> I don't like the concept of deriving the ChangeLog.
>
> Just an idea: What if there was a "make ChangeLog" target that
> triggered on dist but could also be made by anybody who wanted a local
> ChangeLog file?
>
>> I see nothing
>> wrong with generating the ChangeLog by hand and then cut-and-paste
>> the log message into the commit-log.  It's what I've always done, and
>> as far as I can tell it's what everyone else does.  Create once, save
>> twice.
>
> I don't know how to create the changed-path list without visting every
> buffer I changed.  (or recall changing)  I've been using diffstat.
>
> -chris
>

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Derek Atkins
In reply to this post by Chris Shoemaker
Quoting Chris Shoemaker <[hidden email]>:

> On Fri, Dec 02, 2005 at 02:14:30PM -0500, Chris Shoemaker wrote:
>> My preferred implementation of the policy change is currently:
>>
>>   - Continue the pattern Christian started of pulling old ChangeLog
>> entries into archive files.  These files would continue to live in svn.
>
> BTW, I think that for every public release we should also archive the
> ChangeLog at that time.  (That doesn't preclude also archiving for any
> other occasion.)  It doesn't matter to me that the archive files are
> named after years.  If we release version 2.1.1 on Oct. 2, 2006, then
> the ChangeLog up to that release should move from "generated-land" to
> "archive-land" (ChangeLog.2006) at the same time.

I disagree..  If you want to say that it gets rotated at every major/minor
release (e.g. 1.6, 1.8, 2.0) that's fine.  I do not believe that we should
rotate between e.g. 2.0.0 and 2.0.1.

>>   - The "newest" ChangeLog file would be a generated file, made during
>> "make dist", and "make ChangeLog".  It would be generated thusly:
>>     $ svn log -v --xml -r BASE:12076 | xsltproc \
>>         --stringparam strip-prefix "gnucash" --stringparam
>> include-rev "yes" \
>>         ./svn2cl.xsl - > ./ChangeLog
>
> I had to tweak this a bit to get all branches included.  My plan is to
> commit something like this soon that actually generates ChangeLog.svn
> (not ChangeLog).  Then, the next time we rotate the ChangeLog (either
> for a release or for New Years), I want to archive the existing log
> and make new entries "generated".  At that time, the generated file
> will be called ChangeLog.

I would prefer if you refrained at this moment..  I don't think we have
consensus on this change, yet.

> -chris

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Josh Sled
In reply to this post by Derek Atkins
On Fri, 2005-12-02 at 15:59 -0500, Derek Atkins wrote:

> As for how to get the list of files changed, you can just run a diff:
>
>   svn diff | grep '^Index'

`svn status` works quite nicely for figuring out the file-level status.

...jsled
--
http://asynchronous.org/ - `a=jsled; b=asynchronous.org; echo ${a}@${b}`
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Derek Atkins
On Fri, Dec 02, 2005 at 03:59:27PM -0500, Derek Atkins wrote:

> I just thought of the one reason this proposal really bothers me.
> I knew there was something that wasn't sitting right and why I didn't
> think this would work.  It's not that I'm against making developers
> lives easier, but I want to make sure we don't lose something in kind.
>
> I like the ability to specify what changed in each and every file.
> Even when I commit a single feature, I like being able to specify
> what I needed to change in each file to make that feature work.
> I like being able to say:
>
>   foo.c:  did this change
>   bar.c:  did this other change
>   quux.c: made yet another related change
>
> And then have the overarching description:
>
>   Made a bunch of changes to implement _foo_
>
> When you leave the ChangeLog generation out of the developer's hands,
> you can't get this level of detail.  

Sure you can.  Just include those details in the commit message.

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

> As for how to get the list of files changed, you can just run a diff:
>
>  svn diff | grep '^Index'
>
> Personally I feel you should always run an "svn diff | more" prior
> to the commit to make sure you're only committing the change(s) you
> want.  Note that unlike cvs, an svn diff does not touch the network.
> Indeed, you could even create your ChangeLog entry as you're perusing
> your svn diff prior to commit..  Then C-x C-s the ChangeLog buffer,
> M-w to copy the changelog entry, and then C-y once you get the svn commit
> log buffer.  Then just type what you want for the email subject in
> the top line of the buffer and you're done.

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

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] Policy change for ChangeLog

Chris Shoemaker
In reply to this post by Derek Atkins
On Fri, Dec 02, 2005 at 04:10:24PM -0500, Derek Atkins wrote:
> I would prefer if you refrained at this moment..  I don't think we have
> consensus on this change, yet.

Sorry, I pulled the trigger just before I saw your mail.  There does
seem to be support for *some* change.  My change doesn't affect
anything immediately, but it'll give people something to critique.

-chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
12