Re: Rant about ChangeLog entries and commit messages

Re: Rant about ChangeLog entries and commit messages

[Andi Kleen]

Samuel Tardieu <sam@rfc1149.net> writes:


> recent ChangeLog entry in gcc/ChangeLog is:

From my understanding the gcc changelogs serve two purposes these days:

- Force the submitter to read (or rather speed read) the patch again
before sending it out.  
- Serve as a "hash key" to search the gcc-patches archives for the 
real changelog.

The second could be solved far better in many obvious ways, but it's
unclear how to replace the first. Linux kernel doesn't have a solution
for it.

-Andi

Re: Rant about ChangeLog entries and commit messages

[Andi Kleen]

Nicholas Nethercote <njn@csse.unimelb.edu.au> writes:

> Commit logs are basically invisible;

That's just a (fixable) problem in your coding setup. In other
projects it is very common to use tools like cvs annotate / cvsps /
git blame / git log / etc. to find the reasons for why code is the way
it is. In fact in several editors these can be functions on hot
keys. Programming is hard enough as is without ignoring such valuable
information sources. Don't do it.

-Andi

Re: Rant about ChangeLog entries and commit messages

[Nicholas Nethercote]

On Mon, 3 Dec 2007, Andi Kleen wrote:

>> Commit logs are basically invisible;
>
> That's just a (fixable) problem in your coding setup. In other
> projects it is very common to use tools like cvs annotate / cvsps /
> git blame / git log / etc. to find the reasons for why code is the way
> it is. In fact in several editors these can be functions on hot
> keys. Programming is hard enough as is without ignoring such valuable
> information sources. Don't do it.

I didn't say you cannot or should not use these tools.  But a good comment 
on a piece of code sure beats a good commit message, which must be looked at 
separately, and can be fragmented over multiple commits, etc.

Nick

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> I didn't say you cannot or should not use these tools.  But a good comment 
> on a piece of code sure beats a good commit message, which must be looked at 
> separately, and can be fragmented over multiple commits, etc.

I don't see one as "beating" the other because they have very different
purposes.  Sometimes you need one and sometimes you need the other.

The purpose of COMMENTS is to help somebody understand the code as it
stands at some point in time.  In most cases, that means saying WHAT the
code does and WHY (at some level) it does what it does.  Once in a while,
it also means saying why it DOESN'T do something, for example, if it might
appear that there's a simpler way of doing what the code is doing now but
it doesn't work for some subtle reason.  But it's NOT appropriate to put
into comments the historical remark that this code used to have a typo
which caused a miscompilation at some specific place.  However, the commit
log IS the place for that sort of note.

My view is that, in general, the comments are usually the most appropriate
place to put information about how the code currently works and the commit
log is generally the best place for information that contrasts how the code
currently works with how it used to work and provides the motivation for
making the change.  But there are exceptions to both of those generalizations.

Re: Rant about ChangeLog entries and commit messages - better to do something than just complain

[Tim Josling]

On the principle that it's better to do something than just complain...

I monitored the time I spent looking for the emails associated with a
given patch and I found it takes high single digit minutes to find them.
Sometimes you can't find them (which takes a lot longer). I do this a
lot. 

I wrote a little proof-of-concept script to take the mailing list
archives and the ChangeLog files and annotate the ChangeLog files with
the URLs of the probable email containing the patch.

Sample output is here (annotation of the current ChangeLog file). 

http://cobolforgcc.cvs.sourceforge.net/cobolforgcc/gcc/gcc/gcb/gcc_ChangeLog.txt?revision=1.1&view=markup
Or http://tinyurl.com/2v824o
Or http://preview.tinyurl.com/2v824o

The program is here (not much internal documentation at all). Testing
has been limited - in any case, with processing of text written by
people, perfection is not possible.

http://cobolforgcc.cvs.sourceforge.net/cobolforgcc/gcc/gcc/gcb/gcc_mailscan.rb?revision=1.1&view=markup
Or http://tinyurl.com/2yem2u 
Or http://preview.tinyurl.com/2yem2u

It runs in about 25 minutes on my system and uses a few hundred MB of
storage.

Things I learned:

1. There is a lot of data. It's a good thing Ruby 1.9 is a lot faster
than Ruby 1.8.

There are over 100 ChangeLog files in the GCC source, with over 600,000
lines in total. The gcc patches mailing list archives are over 2 GB in
size, and take a considerable time to download.

2. Most patches to ChangeLog have an identifiable email in the archive.
Things get spotty with branches in some cases, also as you go back in
time, and also there is a large gap in the email archives from a while
back.

3. I think this may be a useful thing. If a place could be found to put
the 30MB of files I would be happy to maintain them on a weekly basis or
so. Alternatively I could update the ChangeLog files themselves but I
have reason to suspect that may not be popular.

If nothing else happens I will keep it up-to-date for my own use.

Tim Josling

On Tue, 2007-12-04 at 08:05 -0500, Richard Kenner wrote:
> > I didn't say you cannot or should not use these tools.  But a good comment 
> > on a piece of code sure beats a good commit message, which must be looked at 
> > separately, and can be fragmented over multiple commits, etc.
> 
> I don't see one as "beating" the other because they have very different
> purposes.  Sometimes you need one and sometimes you need the other.
> 
> The purpose of COMMENTS is to help somebody understand the code as it
> stands at some point in time.  In most cases, that means saying WHAT the
> code does and WHY (at some level) it does what it does.  Once in a while,
> it also means saying why it DOESN'T do something, for example, if it might
> appear that there's a simpler way of doing what the code is doing now but
> it doesn't work for some subtle reason.  But it's NOT appropriate to put
> into comments the historical remark that this code used to have a typo
> which caused a miscompilation at some specific place.  However, the commit
> log IS the place for that sort of note.
> 
> My view is that, in general, the comments are usually the most appropriate
> place to put information about how the code currently works and the commit
> log is generally the best place for information that contrasts how the code
> currently works with how it used to work and provides the motivation for
> making the change.  But there are exceptions to both of those generalizations.

Re: Rant about ChangeLog entries and commit messages - better to do something than just complain

[Laurent GUERBY]

On Sat, 2008-02-23 at 20:52 +1100, Tim Josling wrote:
> 3. I think this may be a useful thing. If a place could be found to put
> the 30MB of files I would be happy to maintain them on a weekly basis or
> so. Alternatively I could update the ChangeLog files themselves but I
> have reason to suspect that may not be popular.
> 
> If nothing else happens I will keep it up-to-date for my own use.

Hi,

The GCC Compile Farm can host your scripts, download/processing crontab
and publish the results on a web site.

Instructions on how to apply for a ssh account and misc information
about the current farm status are here:

http://gcc.gnu.org/wiki/CompileFarm

I installed ruby from debian etch on gcc12:

guerby@gcc12:~$ ruby --version
ruby 1.8.5 (2006-08-25) [x86_64-linux]

If you need something else (missing packages, web page, etc...), the
ticket tracker is on gna.org:

https://gna.org/projects/gcc-cfarm/

Hope this helps,

Laurent

Re: Rant about ChangeLog entries and commit messages - better to do something than just complain

[Daniel Jacobowitz]

On Sat, Feb 23, 2008 at 08:52:41PM +1100, Tim Josling wrote:
> I wrote a little proof-of-concept script to take the mailing list
> archives and the ChangeLog files and annotate the ChangeLog files with
> the URLs of the probable email containing the patch.

This is really awesome.  Thank you!  I hope we can get these hosted
and maybe hyperlinked somewhere on a permanent basis.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Rant about ChangeLog entries and commit messages - better to do something than just complain

[Andi Kleen]

On Sat, Feb 23, 2008 at 10:53:53AM -0500, Daniel Jacobowitz wrote:
> On Sat, Feb 23, 2008 at 08:52:41PM +1100, Tim Josling wrote:
> > I wrote a little proof-of-concept script to take the mailing list
> > archives and the ChangeLog files and annotate the ChangeLog files with
> > the URLs of the probable email containing the patch.
> 
> This is really awesome.  Thank you!  I hope we can get these hosted
> and maybe hyperlinked somewhere on a permanent basis.

Agreed. Even nicer would be if the ChangeLogs in the repository
were just updated with this.

-Andi

Re: Rant about ChangeLog entries and commit messages - better to do something than just complain

[Alexandre Oliva]

On Feb 23, 2008, Andi Kleen <andi@firstfloor.org> wrote:

> On Sat, Feb 23, 2008 at 10:53:53AM -0500, Daniel Jacobowitz wrote:
>> On Sat, Feb 23, 2008 at 08:52:41PM +1100, Tim Josling wrote:
>> > I wrote a little proof-of-concept script to take the mailing list
>> > archives and the ChangeLog files and annotate the ChangeLog files with
>> > the URLs of the probable email containing the patch.
>> 
>> This is really awesome.  Thank you!  I hope we can get these hosted
>> and maybe hyperlinked somewhere on a permanent basis.

> Agreed. Even nicer would be if the ChangeLogs in the repository
> were just updated with this.

+1

Thanks, Tim!  Great stuff!

-- 
Alexandre Oliva         http://www.lsd.ic.unicamp.br/~oliva/
FSF Latin America Board Member         http://www.fsfla.org/
Red Hat Compiler Engineer   aoliva@{redhat.com, gcc.gnu.org}
Free Software Evangelist  oliva@{lsd.ic.unicamp.br, gnu.org}

Re: Rant about ChangeLog entries and commit messages

[Robert Kiesling]

> Nicholas Nethercote <njn@csse.unimelb.edu.au> writes:
> 
> > Commit logs are basically invisible;
> 
> That's just a (fixable) problem in your coding setup. In other
> projects it is very common to use tools like cvs annotate / cvsps /
> git blame / git log / etc. to find the reasons for why code is the way
> it is. In fact in several editors these can be functions on hot
> keys. Programming is hard enough as is without ignoring such valuable
> information sources. Don't do it.

Unless there's a good reason _not_ to derive from a source, and there
are several, most of which require a clean-room approach, or a
simulation of it.  I'm just now starting to move over to Subversion,
and I'm sure it has the same ability, to publish CVS logs, though not
via CVS itself.  
C-x v u :)

-- 
Ctalk Home Page: http://www.ctalklang.org/

Re: Rant about ChangeLog entries and commit messages

[Andi Kleen]

kenner@vlsi1.ultra.nyu.edu (Richard Kenner) writes:
>
> Yes, but none of those are visible other than to the development community.
> People who obtain the source distributions of projects don't get to see
> those things.  They DO see things like the ChangeLog format and coding
> and documentation conventions and THOSE are the things that need to be
> common among GNU projects.

It would be probably reasonable these days to require of someone who
wants to do serious development to just download a SVN checkout
for that [or they can use svnweb on http://gcc.gnu.org]

-Andi

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> It would be probably reasonable these days to require of someone who
> wants to do serious development to just download a SVN checkout
> for that [or they can use svnweb on http://gcc.gnu.org]

I agree.  But I think the idea of the ChangeLog is for somewhere just short
of "serious development".  I'm not too far from being willing to agree
that ChangeLog is now hopelessly anachronistic (though I'm not there yet),
but feel that this is really an FSF issue, not a GCC one.

Rant about ChangeLog entries and commit messages

[Samuel Tardieu]

As a recent committer to GCC, I am always surprised to see the content
of ChangeLog entries and commit messages.

I tend to find GCC ChangeLog entries useless. For example, the more
recent ChangeLog entry in gcc/ChangeLog is:

| 2007-11-30  Jan Hubicka  <jh@suse.cz>
| 
|         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
|         flag.

How could a newcomer guess why the gcc_force_collect flag needs to be
reset? Jan posted a useful explanation on gcc-patches, but finding it
by searching the mailing-list is not practical and it is not coupled
with the checkin.

Let's look at the corresponding svn log message, which can be found
with "svn blame" if a particular line needs to be pinpointed:

| r130560 | hubicka | 2007-12-01 22:06:31 +0100 (Sat, 01 Dec 2007) | 4 lines
| 
|         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
|         flag.

Ok, same information is mirrored here, not useful. Let's look at the
change itself then:

| Index: gcc/ChangeLog
| ===================================================================
| --- gcc/ChangeLog       (revision 130559)
| +++ gcc/ChangeLog       (revision 130560)
| @@ -1,3 +1,8 @@
| +2007-11-30  Jan Hubicka  <jh@suse.cz>
| +
| +       * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
| +       flag.
| +
|  2007-11-30  Seongbae Park <seongbae.park@gmail.com>
|  
|         PR rtl-optimization/34171
| Index: gcc/ggc-common.c
| ===================================================================
| --- gcc/ggc-common.c    (revision 130559)
| +++ gcc/ggc-common.c    (revision 130560)
| @@ -1018,5 +1018,6 @@
|    fprintf (stderr, "%-48s %10s       %10s       %10s       %10s       %10s\n",
|            "source location", "Garbage", "Freed", "Leak", "Overhead", "Times");
|    fprintf (stderr, "-------------------------------------------------------\n")
| ;
| +  ggc_force_collect = false;
|  #endif
|  }

Ok, still the same information because of the ChangeLog diff, and we
can see that the change shows that... gcc_force_collect is reset. Wow!

Now, compare that with Jan's message on the list:

| pre-ipa-mem-reports force GGC to be done at each invokation in order to
| collect data on live memory references, but forgets to reset the flag
| after done.  This means that compiler continues GGCcollecting and works
| slowly.

This *is* the information I would expect to be present somewhere in
GCC history. A clear and detailed information on why the change was
necessary. Sure, in some case the checkin references a PR, but the PR
often contains information of what didn't work before the change and
the same information which is already repeated three times (ChangeLog,
svn log and svn diff).

Compare this to a typical commit in the Linux kernel:

| commit b1812582ba94b5f377d5d3cec7646cc17d84e733
| Author: Joachim Fenkes <fenkes@de.ibm.com>
| Date:   Fri Nov 30 16:19:41 2007 -0800
| 
|     IB/ehca: Fix static rate if path faster than link
|     
|     The formula would yield -1 if the path is faster than the link, which
|     is wrong in a bad way (max throttling).  Clamp to 0, which is the
|     correct value.
|     
|     Signed-off-by: Joachim Fenkes <fenkes@de.ibm.com>
|     Signed-off-by: Roland Dreier <rolandd@cisco.com>
| 
| diff --git a/drivers/infiniband/hw/ehca/ehca_av.c b/drivers/infiniband/hw/ehca/ehca_av.c
| index 453eb99..f7782c8 100644
| --- a/drivers/infiniband/hw/ehca/ehca_av.c
| +++ b/drivers/infiniband/hw/ehca/ehca_av.c
| @@ -76,8 +76,12 @@ int ehca_calc_ipd(struct ehca_shca *shca, int port,
|  
|  	link = ib_width_enum_to_int(pa.active_width) * pa.active_speed;
|  
| -	/* IPD = round((link / path) - 1) */
| -	*ipd = ((link + (path >> 1)) / path) - 1;
| +	if (path >= link)
| +		/* no need to throttle if path faster than link */
| +		*ipd = 0;
| +	else
| +		/* IPD = round((link / path) - 1) */
| +		*ipd = ((link + (path >> 1)) / path) - 1;
|  
|  	return 0;
|  }

What do we have here? A one-line high-level description identifying
what has been done, a synthetic analysis of the problem cause and its
solution, and the audit trail with the Signed-off-by lines (which in
the Linux case is more important than in GCC as copyrights are not
assigned to one entity).

Linux doesn't use ChangeLog, but its history is much more useful to
developers and casual observers than GCC one. And it could be done
for GCC (with SVN) as well.

Maybe we should consider dropping ChangeLogs and using better checkin
messages.

  Sam

Re: Rant about ChangeLog entries and commit messages

[Andreas Schwab]

Samuel Tardieu <sam@rfc1149.net> writes:

> As a recent committer to GCC, I am always surprised to see the content
> of ChangeLog entries and commit messages.
>
> I tend to find GCC ChangeLog entries useless. For example, the more
> recent ChangeLog entry in gcc/ChangeLog is:
>
> | 2007-11-30  Jan Hubicka  <jh@suse.cz>
> | 
> |         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
> |         flag.
>
> How could a newcomer guess why the gcc_force_collect flag needs to be
> reset?

That is supposed to be written in a comment.  The change log entry
should describe _what_ is being changed, so that you can find out when a
particular change was made.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu]

On  2/12, Andreas Schwab wrote:

| That is supposed to be written in a comment.  The change log entry
| should describe _what_ is being changed, so that you can find out when a
| particular change was made.

This should be the job of the VCS, e.g. "svn log" and "svn blame".
Moreover, ChangeLogs are organized by directories. You have to look
at the "svn log" to see if a test corresponds to a code change and
identify it.

Re: Rant about ChangeLog entries and commit messages

[Hans-Peter Nilsson]

On Sun, 2 Dec 2007, Samuel Tardieu wrote:
> On  2/12, Andreas Schwab wrote:
>
> | That is supposed to be written in a comment.  The change log entry
> | should describe _what_ is being changed, so that you can find out when a
> | particular change was made.
>
> This should be the job of the VCS, e.g. "svn log" and "svn blame".
> Moreover, ChangeLogs are organized by directories. You have to look
> at the "svn log" to see if a test corresponds to a code change and
> identify it.

The comment *in the code* is lacking, other than that I don't
see much point in your rant; it's all been said before, for one.
It usually takes a while for newcomers to understand the
process, in particular the what-not-why of ChangeLogs... ;)

brgds, H-P

Re: Rant about ChangeLog entries and commit messages

[Robert Dewar]

Hans-Peter Nilsson wrote:

> The comment *in the code* is lacking, other than that I don't
> see much point in your rant; it's all been said before, for one.
> It usually takes a while for newcomers to understand the
> process, in particular the what-not-why of ChangeLogs... ;)

I actually think that often it is helpful to have the why in
changelogs. Yes, this should never take the place of commments
in the code, and that is a failing you want to watch out for,
but sometimes a global motivation for a chage would make a
changelog entry easier to understand.

If all the changelog entry says is something like

(xyz): new function

I don't see much point, since a diff can always easily tell
you *what* was changed.
> 
> brgds, H-P

Re: Rant about ChangeLog entries and commit messages

[DJ Delorie]

Robert Dewar <dewar@adacore.com> writes:
> I don't see much point, since a diff can always easily tell
> you *what* was changed.

A changelog does help recreate a change *set* though, since CVS is
lacking such a thing.  Thus, the CL helps you determine what files to
diff.

True that SVN solves part of that, but SVN is not universal.

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> If all the changelog entry says is something like
> 
> (xyz): new function
> 
> I don't see much point, since a diff can always easily tell
> you *what* was changed.

The point is that, by just looking at the ChangeLog, you can tell when
xyz was introduced and by whom.  I've used that quite a number of
times.  Moreover, as was pointed out, when you have a source
distribution, you don't get the commit logs, just the ChangeLog.

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On 12/2/07, Richard Kenner <kenner@vlsi1.ultra.nyu.edu> wrote:
> > If all the changelog entry says is something like
> >
> > (xyz): new function
> >
> > I don't see much point, since a diff can always easily tell
> > you *what* was changed.
>
> The point is that, by just looking at the ChangeLog, you can tell when
> xyz was introduced and by whom.  I've used that quite a number of
> times.  Moreover, as was pointed out, when you have a source
> distribution, you don't get the commit logs, just the ChangeLog.
There are in fact, already programs that will generate GNU format
changelogs from svn log (see http://ch.tudelft.nl/~arthur/svn2cl/)
It would be very easy to run these as part of the release process.

Last time I looked, this is in fact how some GNU projects generate
ChangeLog for distribution!

>

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> There are in fact, already programs that will generate GNU format
> changelogs from svn log (see http://ch.tudelft.nl/~arthur/svn2cl/)
> It would be very easy to run these as part of the release process.

Sure, but I think that's bad for this project since I support the idea
that the svn log should contain additional information that's not part
of what the GNU project wants in ChangeLog.

Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu]

Sam> How could a newcomer guess why the gcc_force_collect flag needs to
Sam> be reset?

Andreas> That is supposed to be written in a comment.  The change log
Andreas> entry should describe _what_ is being changed, so that you
Andreas> can find out when a particular change was made.

Out of curiosity, I looked for an example with one of your own commits
in the Linux kernel tree and I found one: I think
http://tinyurl.com/2j7lt7 is a very helpful explanation of the
corresponding change (http://tinyurl.com/2tpw8l).

Someone trying to fix a similar bug in another driver will benefit
from having this message in the VCS history. A comment in the code
would probably have been much shorter than this explanation and would
probably not contain the "headphone", "line out" and "muted" words.

Once again, I agree that the current mechanism works for GCC
developers, but I think it could be much better if:

   1- commit messages didn't duplicate ChangeLog entries (maybe by
      getting rid of ChangeLogs)

   2- commit messages contained a synthetic information such as the one
      provided for peer-review

I'm not trying to launch a revolution in the GCC development process,
I'm only comparing two ways of documenting changes as they are
committed and explaining why I find the Linux way of doing it more
useful.

As a side note, I know several (sick?) people (including myself) who
casually read the Linux kernel RSS feed in their RSS aggregator and
find it very insightful (if you exclude the "Merge" messages) while
lighter than reading the whole linux-kernel mailing-list. People
reading this can look at

  http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=atom
  
with RSS-capable software to see what I mean. The GCC ChangeLogs, even
when aggregated, aren't as nice to read when you're having breakfast :)

 Sam

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> > How could a newcomer guess why the gcc_force_collect flag needs to be
> > reset?
> 
> That is supposed to be written in a comment.  The change log entry
> should describe _what_ is being changed, so that you can find out when a
> particular change was made.

Not quite.  The comments are supposed to say why the code is doing what
it's doing (and, where it's helpful, why it ISN'T doing something else).
Purely historical references in the comments that don't serve to clarify
the present code are discouraged.  (We don't want comments turning in a
blog, for example.)

I view the description in the gcc-patches message as PART of the CM history
of GCC in that IT'S the place to go to get this information.  What's
unfortunate, I think, is that there's no easy way to find this message from
the CM revision number.

Re: Rant about ChangeLog entries and commit messages

[Bernd Schmidt]

Richard Kenner wrote:
>>> How could a newcomer guess why the gcc_force_collect flag needs to be
>>> reset?
>> That is supposed to be written in a comment.  The change log entry
>> should describe _what_ is being changed, so that you can find out when a
>> particular change was made.
> 
> Not quite.  The comments are supposed to say why the code is doing what
> it's doing (and, where it's helpful, why it ISN'T doing something else).
> Purely historical references in the comments that don't serve to clarify
> the present code are discouraged.  (We don't want comments turning in a
> blog, for example.)
> 
> I view the description in the gcc-patches message as PART of the CM history
> of GCC in that IT'S the place to go to get this information.  What's
> unfortunate, I think, is that there's no easy way to find this message from
> the CM revision number.

I think that's Samuel's point - it would be much better to have them in
the commit log.  FWIW, I agree completely - I've never found ChangeLogs
useful, I hate writing them, and I think the linux-kernel guys these
days generally have much better checkin messages than we do.


Bernd
-- 
This footer brought to you by insane German lawmakers.
Analog Devices GmbH      Wilhelm-Wagenfeld-Str. 6      80807 Muenchen
Sitz der Gesellschaft Muenchen, Registergericht Muenchen HRB 40368
Geschaeftsfuehrer Thomas Wessel, William A. Martin, Margaret Seif

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> FWIW, I agree completely - I've never found ChangeLogs useful, I hate
> writing them, and I think the linux-kernel guys these days generally have
> much better checkin messages than we do. 

I guess nobody really loves writing ChangeLog entries, but in my opinion there 
are quite effective "executive summaries" for the patches and helpful to the 
reader/reviewer.  Please let's not throw the baby with the bath's water.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Robert Kiesling]

[ Charset ISO-8859-1 unsupported, converting... ]
> > FWIW, I agree completely - I've never found ChangeLogs useful, I hate
> > writing them, and I think the linux-kernel guys these days generally have
> > much better checkin messages than we do. 
> 
> I guess nobody really loves writing ChangeLog entries, but in my opinion there 
> are quite effective "executive summaries" for the patches and helpful to the 
> reader/reviewer.  Please let's not throw the baby with the bath's water.

If there's a mechanism to filter checkin messages to ChangeLog summaries, 
I would be happy to use it - in cases of multiple packages, especially, it's 
important to know what changes were made, when, and when the changes propagated
through packages and releases, and where they got to, occasionally.  Anybody
know of a useful, built-in mechanism for this task?

-- 
Ctalk Home Page: http://ctalk-lang.sourceforge.net

Re: Rant about ChangeLog entries and commit messages

[tim]

On Sun, 2007-12-02 at 09:26 -0500, Robert Kiesling wrote: 
> > I guess nobody really loves writing ChangeLog entries, but in my opinion there 
> > are quite effective "executive summaries" for the patches and helpful to the 
> > reader/reviewer.  Please let's not throw the baby with the bath's water.
> 
> If there's a mechanism to filter checkin messages to ChangeLog summaries, 
> I would be happy to use it - in cases of multiple packages, especially, it's 
> important to know what changes were made, when, and when the changes propagated
> through packages and releases, and where they got to, occasionally.  Anybody
> know of a useful, built-in mechanism for this task?
> 

Personally I find it slow and inefficient tracing through why a given
change was made. It is just a slow process searching and sometimes I
don't bother because it is so inconvenient. The ChangeLog entries
provide little help and there does not seem to be a good alternative. If
there is a good alternative no-one has said what it is so far.

As people have pointed out, the RCSs pretty well cover the "what" these
days. And writing changelog entries, which largely duplicate this
information, is time-consuming and tedious. And there are of of little
to no value to me at least.

The coding standards do allow, in some cases, that giving some context
would be useful:

> See also what the GNU Coding Standards have to say about what goes in
> ChangeLogs; in particular, descriptions of the purpose of code and
> changes should go in comments rather than the ChangeLog, though a
> single line overall description of the changes may be useful above the
> ChangeLog entry for a large batch of changes.

I personally would strongly favour each ChangeLog entry having a single
line of context. This could be the PR number or a single line giving the
purpose of the change or what bigger change it is part of. 

As pointed out by Zach Weinberg in his paper "A Maintenance Programmer's
View of GCC", there are many impediments to contributing to GCC.

http://www.linux.org.uk/~ajh/gcc/gccsummit-2003-proceedings.pdf

Things are not much better than they were when Zach wrote his paper. This small change would be one positive step n the right direction, IMHO.

Tim Josling

Re: Rant about ChangeLog entries and commit messages

[Robert Kiesling]

> On Sun, 2007-12-02 at 09:26 -0500, Robert Kiesling wrote: 
> > > I guess nobody really loves writing ChangeLog entries, but in my opinion there 
> > > are quite effective "executive summaries" for the patches and helpful to the 
> > > reader/reviewer.  Please let's not throw the baby with the bath's water.
> > 
> > If there's a mechanism to filter checkin messages to ChangeLog summaries, 
> > I would be happy to use it - in cases of multiple packages, especially, it's 
> > important to know what changes were made, when, and when the changes propagated
> > through packages and releases, and where they got to, occasionally.  Anybody
> > know of a useful, built-in mechanism for this task?
> > 
> 
> Personally I find it slow and inefficient tracing through why a given
> change was made. It is just a slow process searching and sometimes I
> don't bother because it is so inconvenient. The ChangeLog entries
> provide little help and there does not seem to be a good alternative. If
> there is a good alternative no-one has said what it is so far.
> 
> As people have pointed out, the RCSs pretty well cover the "what" these
> days. And writing changelog entries, which largely duplicate this
> information, is time-consuming and tedious. And there are of of little
> to no value to me at least.
> 
> The coding standards do allow, in some cases, that giving some context
> would be useful:
> 
> > See also what the GNU Coding Standards have to say about what goes in
> > ChangeLogs; in particular, descriptions of the purpose of code and
> > changes should go in comments rather than the ChangeLog, though a
> > single line overall description of the changes may be useful above the
> > ChangeLog entry for a large batch of changes.
> 
> I personally would strongly favour each ChangeLog entry having a single
> line of context. This could be the PR number or a single line giving the
> purpose of the change or what bigger change it is part of. 
> 
> As pointed out by Zach Weinberg in his paper "A Maintenance Programmer's
> View of GCC", there are many impediments to contributing to GCC.
> 
> http://www.linux.org.uk/~ajh/gcc/gccsummit-2003-proceedings.pdf
> 
> Things are not much better than they were when Zach wrote his paper. This small change would be one positive step n the right direction, IMHO.

One line of reference would be sufficient provided that branches other
than the main development trunk stick to revisions in that branch only.
I haven't glanced through the references yet, but maintenance programming
is considerably different than writing new code, or even modifying 
someone else's code.  If it's the latter you're trying to achieve, or 
anticipate achieving, then an accurate line of reference would be most 
helpful.  

Unfortunately, then, _someone_ has to maintain the comments accurately.
I wouldn't care to say who (whom?)... just... someone.  :)

-- 
Ctalk Home Page: http://ctalk-lang.sourceforge.net

Re: Rant about ChangeLog entries and commit messages

[Robert Dewar]

Eric Botcazou wrote:
>> FWIW, I agree completely - I've never found ChangeLogs useful, I hate
>> writing them, and I think the linux-kernel guys these days generally have
>> much better checkin messages than we do. 
> 
> I guess nobody really loves writing ChangeLog entries, but in my opinion there 
> are quite effective "executive summaries" for the patches and helpful to the 
> reader/reviewer.  Please let's not throw the baby with the bath's water.

Right, but to me an important part of the "executive summary" is why you
did it. You don't go to the boss and say "I fired Joe", you go and say
"I fired Joe, because ..."
> 

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On 12/2/07, Bernd Schmidt <bernds_cb1@t-online.de> wrote:
> Richard Kenner wrote:
> >>> How could a newcomer guess why the gcc_force_collect flag needs to be
> >>> reset?
> >> That is supposed to be written in a comment.  The change log entry
> >> should describe _what_ is being changed, so that you can find out when a
> >> particular change was made.
> >
> > Not quite.  The comments are supposed to say why the code is doing what
> > it's doing (and, where it's helpful, why it ISN'T doing something else).
> > Purely historical references in the comments that don't serve to clarify
> > the present code are discouraged.  (We don't want comments turning in a
> > blog, for example.)
> >
> > I view the description in the gcc-patches message as PART of the CM history
> > of GCC in that IT'S the place to go to get this information.  What's
> > unfortunate, I think, is that there's no easy way to find this message from
> > the CM revision number.
>
> I think that's Samuel's point - it would be much better to have them in
> the commit log.  FWIW, I agree completely - I've never found ChangeLogs
> useful, I hate writing them, and I think the linux-kernel guys these
> days generally have much better checkin messages than we do.
>

+1.

I have never, in 7 years of working on and debugging gcc, found the
ChangeLog to be useful in debugging a problem.
They are like a useless version of svn diff output.
If I wanted to know what the change did, i'd look at what the change
did.  The ChangeLog is well nigh useless even for that compared to the
actual diff.

I'd go even further, and say if the GNU coding standards say we
shouldn't be putting descriptions of why we are changing things in the
ChangeLog, than they should be changed and should be ignored on this
point until they do.  Pointing to them as the if they are The One True
Way seems very suspect to me.  After all, how else would they ever
improve if nobody tries anything different?

--Dan

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> I'd go even further, and say if the GNU coding standards say we
> shouldn't be putting descriptions of why we are changing things in the
> ChangeLog, than they should be changed and should be ignored on this
> point until they do.  Pointing to them as the if they are The One True
> Way seems very suspect to me.  After all, how else would they ever
> improve if nobody tries anything different?

The people who wrote them presumably thought about these issues, too.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On 12/2/07, Eric Botcazou <ebotcazou@libertysurf.fr> wrote:
> > I'd go even further, and say if the GNU coding standards say we
> > shouldn't be putting descriptions of why we are changing things in the
> > ChangeLog, than they should be changed and should be ignored on this
> > point until they do.  Pointing to them as the if they are The One True
> > Way seems very suspect to me.  After all, how else would they ever
> > improve if nobody tries anything different?
>
> The people who wrote them presumably thought about these issues, too.

Right, because surely one size fits all projects and possibilities,
and  workflow and processes have certainly not changed since then.

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> Right, because surely one size fits all projects and possibilities,

It was supposed to be the Coding Standards for The GNU Project.

> and  workflow and processes have certainly not changed since then.

In my opinion, it's now easier to work around their perceived deficiencies.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On 12/2/07, Eric Botcazou <ebotcazou@libertysurf.fr> wrote:
> > Right, because surely one size fits all projects and possibilities,
>
> It was supposed to be the Coding Standards for The GNU Project.

Sorry, but again, this is not a good enough justification to me.
We do a lot of things different than "The GNU Project".
So do plenty of parts of the "official GNU project".
They use different coding standards, bug tracking systems, version
control systems, checkin policies, etc, than each other.

If you have a better justification, i'd love to hear it.

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> If you have a better justification, i'd love to hear it.

Justification for what?  I only tried to explain to Sam why we do things the 
way we do, I didn't write the GNU Coding Standards either.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> Sorry, but again, this is not a good enough justification to me.
> We do a lot of things different than "The GNU Project".
> So do plenty of parts of the "official GNU project".
> They use different coding standards, bug tracking systems, version
> control systems, checkin policies, etc, than each other.

Yes, but none of those are visible other than to the development community.
People who obtain the source distributions of projects don't get to see
those things.  They DO see things like the ChangeLog format and coding
and documentation conventions and THOSE are the things that need to be
common among GNU projects.

In my view, ChangeLog is mostly "write-only" from a developer's
perspective.  It's a document that the GNU project requires us to produce
for the benefit of people who DON'T want access to our checkin-logs, bug
tracking information, and mailing lsits.  But for our own development
purposes, we use the above information much more than ChangeLog.

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On 12/3/07, Richard Kenner <kenner@vlsi1.ultra.nyu.edu> wrote:
> > Sorry, but again, this is not a good enough justification to me.
> > We do a lot of things different than "The GNU Project".
> > So do plenty of parts of the "official GNU project".
> > They use different coding standards, bug tracking systems, version
> > control systems, checkin policies, etc, than each other.
>
> Yes, but none of those are visible other than to the development community.
> People who obtain the source distributions of projects don't get to see
> those things.  They DO see things like the ChangeLog format and coding
> and documentation conventions and THOSE are the things that need to be
> common among GNU projects.

Except they aren't, across large parts of the GNU project.

You may find it the same in the "traditional" parts of the GNU project
(IE coreutils, emacs, etc).
It's certainly not the same across any of the newer parts of the GNU project.

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> Except they aren't, across large parts of the GNU project.
> 
> You may find it the same in the "traditional" parts of the GNU project
> (IE coreutils, emacs, etc).
> It's certainly not the same across any of the newer parts of the GNU project.

Perhaps, but GCC has always been considered, like emacs, to be one of
the most central parts of the GCC project and I think it'd be very wrong
for us not follow their wishes in standardization areas.

Re: Rant about ChangeLog entries and commit messages

[Robert Kiesling]

[ Charset ISO-8859-1 unsupported, converting... ]
> On 12/3/07, Richard Kenner <kenner@vlsi1.ultra.nyu.edu> wrote:
> > > Sorry, but again, this is not a good enough justification to me.
> > > We do a lot of things different than "The GNU Project".
> > > So do plenty of parts of the "official GNU project".
> > > They use different coding standards, bug tracking systems, version
> > > control systems, checkin policies, etc, than each other.
> >
> > Yes, but none of those are visible other than to the development community.
> > People who obtain the source distributions of projects don't get to see
> > those things.  They DO see things like the ChangeLog format and coding
> > and documentation conventions and THOSE are the things that need to be
> > common among GNU projects.
> 
> Except they aren't, across large parts of the GNU project.
> 
> You may find it the same in the "traditional" parts of the GNU project
> (IE coreutils, emacs, etc).
> It's certainly not the same across any of the newer parts of the GNU project.

That's because, although the GNU project strictly - and correctly,
experience has shown - monitors its code base, with the propagation 
of the Free Software development model, newer Free Software 
contributors who maintain their code on sites like sourceforge.net,
are subject to commercial pressures that the older, ivory-tower
authors in general are shielded from.

It's impossible to convince someone who wants your "niche" for a
quickie IPO that maintaining code for more than two or three years 
is worth the investment.

-- 
Ctalk Home Page: http://www.ctalklang.org/

Re: Rant about ChangeLog entries and commit messages

[Robert Dewar]

Robert Kiesling wrote:

> That's because, although the GNU project strictly - and correctly,
> experience has shown - monitors its code base, with the propagation 
> of the Free Software development model, newer Free Software 
> contributors who maintain their code on sites like sourceforge.net,
> are subject to commercial pressures that the older, ivory-tower
> authors in general are shielded from.
> 
> It's impossible to convince someone who wants your "niche" for a
> quickie IPO that maintaining code for more than two or three years 
> is worth the investment.

I don't treally understand this commment, we are talking about
improving the maintainability here, and what people are saying
is that some other parts of the project have already moved in
this direction.

Re: Rant about ChangeLog entries and commit messages

[Jeffrey Law]

On Mon, 2007-12-03 at 08:29 -0500, Richard Kenner wrote:
> > Sorry, but again, this is not a good enough justification to me.
> > We do a lot of things different than "The GNU Project".
> > So do plenty of parts of the "official GNU project".
> > They use different coding standards, bug tracking systems, version
> > control systems, checkin policies, etc, than each other.
> 
> Yes, but none of those are visible other than to the development community.
> People who obtain the source distributions of projects don't get to see
> those things.  They DO see things like the ChangeLog format and coding
> and documentation conventions and THOSE are the things that need to be
> common among GNU projects.
> 
> In my view, ChangeLog is mostly "write-only" from a developer's
> perspective.  It's a document that the GNU project requires us to produce
> for the benefit of people who DON'T want access to our checkin-logs, bug
> tracking information, and mailing lsits.  But for our own development
> purposes, we use the above information much more than ChangeLog.
Right.

I don't necessarily want verbose ChangeLogs -- there are times I just 
want to know what changed and who changed it.  That's nice and easy to
extract from the ChangeLog.

Sometimes I want to look at the code/comments.  Obviously I go to the 
source to read those.

Sometimes I want even more information for a particularly complex
or controversial change -- in those cases I go back to the mailing list
archives and review the discussion(s) leading to changes to the code.


Each repository of information provides a different level of detail and
each (IMHO) has its place/utility.

Jeff

Re: Rant about ChangeLog entries and commit messages

[Alexandre Oliva]

On Dec  3, 2007, kenner@vlsi1.ultra.nyu.edu (Richard Kenner) wrote:

> In my view, ChangeLog is mostly "write-only" from a developer's
> perspective.  It's a document that the GNU project requires us to produce
> for

... a good example of compliance with the GPL:

  5. Conveying Modified Source Versions.

    a) The work must carry prominent notices stating that you modified
    it, and giving a relevant date.


FWIW, I've used ChangeLogs to find problems a number of times in my 14
years of work in GCC, and I find them very useful.  When I need more
details, web-searching for the author of the patch and some relevant
keywords in the ChangeLog will often point at the relevant e-mail, so
burdening people with adding a direct URL seems pointless to me.  It's
pessimizing the common case for a small optimization in far less
common cases.

-- 
Alexandre Oliva         http://www.lsd.ic.unicamp.br/~oliva/
FSF Latin America Board Member         http://www.fsfla.org/
Red Hat Compiler Engineer   aoliva@{redhat.com, gcc.gnu.org}
Free Software Evangelist  oliva@{lsd.ic.unicamp.br, gnu.org}

Re: Rant about ChangeLog entries and commit messages

[NightStrike]

On 12/15/07, Alexandre Oliva <aoliva@redhat.com> wrote:
> On Dec  3, 2007, kenner@vlsi1.ultra.nyu.edu (Richard Kenner) wrote:
>
> > In my view, ChangeLog is mostly "write-only" from a developer's
> > perspective.  It's a document that the GNU project requires us to produce
> > for
>
> ... a good example of compliance with the GPL:
>
>  5. Conveying Modified Source Versions.
>
>    a) The work must carry prominent notices stating that you modified
>    it, and giving a relevant date.
>
>
> FWIW, I've used ChangeLogs to find problems a number of times in my 14
> years of work in GCC, and I find them very useful.  When I need more
> details, web-searching for the author of the patch and some relevant
> keywords in the ChangeLog will often point at the relevant e-mail, so
> burdening people with adding a direct URL seems pointless to me.  It's
> pessimizing the common case for a small optimization in far less
> common cases.

Maybe Changelogs should be reserved for important changes.  For
instance, something like "Fixed a typo" is a complete waste.  I doubt
anyone looks ta a Changelog to see if someone fixed a typo recently or
at any point in the past.  Perhaps there could be some criteria so
that not every single iota gets a log entry.

Re: Rant about ChangeLog entries and commit messages

[Alexandre Oliva]

On Dec 16, 2007, NightStrike <nightstrike@gmail.com> wrote:

> On 12/15/07, Alexandre Oliva <aoliva@redhat.com> wrote:
>> ... a good example of compliance with the GPL:
>> 
>> 5. Conveying Modified Source Versions.
>> 
>> a) The work must carry prominent notices stating that you modified
>> it, and giving a relevant date.

> Maybe Changelogs should be reserved for important changes.  For
> instance, something like "Fixed a typo" is a complete waste.  I doubt
> anyone looks ta a Changelog to see if someone fixed a typo recently or
> at any point in the past.

I've done that, while backporting patches.  Oftentimes there are small
fixes on top of larger patches, and you want to credit those who made
the small fixes, and you want to be sure you caught them next time you
look at the patch.  ChangeLogs for these are useful for this purpose.

> Perhaps there could be some criteria so that not every single iota
> gets a log entry.

How would leaving changes out comply with 5a above?

-- 
Alexandre Oliva         http://www.lsd.ic.unicamp.br/~oliva/
FSF Latin America Board Member         http://www.fsfla.org/
Red Hat Compiler Engineer   aoliva@{redhat.com, gcc.gnu.org}
Free Software Evangelist  oliva@{lsd.ic.unicamp.br, gnu.org}

Re: Rant about ChangeLog entries and commit messages

[NightStrike]

On 12/16/07, Alexandre Oliva <aoliva@redhat.com> wrote:
> On Dec 16, 2007, NightStrike <nightstrike@gmail.com> wrote:
>
> > On 12/15/07, Alexandre Oliva <aoliva@redhat.com> wrote:
> >> ... a good example of compliance with the GPL:
> >>
> >> 5. Conveying Modified Source Versions.
> >>
> >> a) The work must carry prominent notices stating that you modified
> >> it, and giving a relevant date.
>
> > Maybe Changelogs should be reserved for important changes.  For
> > instance, something like "Fixed a typo" is a complete waste.  I doubt
> > anyone looks ta a Changelog to see if someone fixed a typo recently or
> > at any point in the past.
>
> I've done that, while backporting patches.  Oftentimes there are small
> fixes on top of larger patches, and you want to credit those who made
> the small fixes, and you want to be sure you caught them next time you
> look at the patch.  ChangeLogs for these are useful for this purpose.
>
> > Perhaps there could be some criteria so that not every single iota
> > gets a log entry.
>
> How would leaving changes out comply with 5a above?

It wouldn't without some "creative interpretations".

Re: Rant about ChangeLog entries and commit messages

[Tim Josling]

On Sat, 2007-12-15 at 20:54 -0200, Alexandre Oliva wrote:
> On Dec  3, 2007, kenner@vlsi1.ultra.nyu.edu (Richard Kenner) wrote:
> 
> > In my view, ChangeLog is mostly "write-only" from a developer's
> > perspective.  It's a document that the GNU project requires us to
> produce
> > for
> 
> ... a good example of compliance with the GPL:
> 
>   5. Conveying Modified Source Versions.
> 
>     a) The work must carry prominent notices stating that you modified
>     it, and giving a relevant date.
> 

(Minor quibble) As copyright owner of GCC, the FSF is not bound by the
conditions of the licence it grants in the same way as licencees are
bound. So I don't think this provision in itself would mandate that
those who have copyright assignments to the FSF record their changes.

I don't hear anyone arguing that people should not record what they
changes and when. The question is whether it is sufficient.

I just started using git locally, and I keep thinking it would be really
great to have something like "git blame" for gcc. The command "git
blame" gives you a listing of who changed each line of the file and
when, and also gives the commit id. From that all can be revealed.

> 
> FWIW, I've used ChangeLogs to find problems a number of times in my 14
> years of work in GCC, and I find them very useful.  When I need more
> details, web-searching for the author of the patch and some relevant
> keywords in the ChangeLog will often point at the relevant e-mail, so
> burdening people with adding a direct URL seems pointless to me.  It's
> pessimizing the common case for a small optimization in far less
> common cases.
> 

This may possibly work when the mailing list entries exist and are
accessible. 

However they are only available AFAIK from 1998. GCC has been going for
2-3 times as long as that. And there is at least one significant gap:
February 2004 up to and including this message
http://gcc.gnu.org/ml/gcc-patches/2004-02/msg02288.html.

In my experience, when documentation is not stored with the source code,
it often gets lost.

When a person is offline the mailing list htmls are not available.

I have an idea to resolve this that I am working on... more in due
course if it comes to anything.

Tim Josling

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On Dec 25, 2007 1:57 PM, Tim Josling <tejgcc@westnet.com.au> wrote:
> On Sat, 2007-12-15 at 20:54 -0200, Alexandre Oliva wrote:
> > On Dec  3, 2007, kenner@vlsi1.ultra.nyu.edu (Richard Kenner) wrote:
> >
> > > In my view, ChangeLog is mostly "write-only" from a developer's
> > > perspective.  It's a document that the GNU project requires us to
> > produce
> > > for
> >
> > ... a good example of compliance with the GPL:
> >
> >   5. Conveying Modified Source Versions.
> >
> >     a) The work must carry prominent notices stating that you modified
> >     it, and giving a relevant date.
> >
>
> (Minor quibble) As copyright owner of GCC, the FSF is not bound by the
> conditions of the licence it grants in the same way as licencees are
> bound. So I don't think this provision in itself would mandate that
> those who have copyright assignments to the FSF record their changes.
>
> I don't hear anyone arguing that people should not record what they
> changes and when. The question is whether it is sufficient.
>
> I just started using git locally, and I keep thinking it would be really
> great to have something like "git blame" for gcc.

svn already has blame :)

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> (Minor quibble) As copyright owner of GCC, the FSF is not bound by the
> conditions of the licence it grants in the same way as licencees are
> bound. So I don't think this provision in itself would mandate that
> those who have copyright assignments to the FSF record their changes.

I was hoping nobody would notice that.  ;-)

> I don't hear anyone arguing that people should not record what they
> changes and when. The question is whether it is sufficient.

I think we all agree that it isn't, but figuring out where and what to
put elsewhere has been tricky.

Re: Rant about ChangeLog entries and commit messages

[Robert Dewar]

Richard Kenner wrote:
>> (Minor quibble) As copyright owner of GCC, the FSF is not bound by the
>> conditions of the licence it grants in the same way as licencees are
>> bound. So I don't think this provision in itself would mandate that
>> those who have copyright assignments to the FSF record their changes.
> 
> I was hoping nobody would notice that.  ;-)

Actually I think this is wrong, the FSF holds the copyright
by virtue of a copyright assignment which contains the
guarantee that the software will be distributed under the
GPL (at least that's my recollection of the assignment
document).

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> >> (Minor quibble) As copyright owner of GCC, the FSF is not bound by the
> >> conditions of the licence it grants in the same way as licencees are
> >> bound. So I don't think this provision in itself would mandate that
> >> those who have copyright assignments to the FSF record their changes.
> > 
> > I was hoping nobody would notice that.  ;-)
> 
>
> Actually I think this is wrong, the FSF holds the copyright by virtue of
> a copyright assignment which contains the guarantee that the software
> will be distributed under the GPL (at least that's my recollection of the
> assignment document).

That part's true, but the cited part of the GPL applies only to somebody
who makes a *modification* to the work of the copyright holder and
redistributes that work.  Such a condition doesn't apply to the FSF, who
*is* the copyright holder.

Re: Rant about ChangeLog entries and commit messages

[Alexandre Oliva]

On Dec 25, 2007, Tim Josling <tejgcc@westnet.com.au> wrote:

> On Sat, 2007-12-15 at 20:54 -0200, Alexandre Oliva wrote:
>> ... a good example of compliance with the GPL:

>> 5. Conveying Modified Source Versions.
>> 
>> a) The work must carry prominent notices stating that you modified
>> it, and giving a relevant date.

> (Minor quibble) As copyright owner of GCC, the FSF is not bound by the
> conditions of the licence it grants in the same way as licencees are
> bound.

Of course.  That's exactly why I wrote "good example".  It wouldn't be
nice if the FSF itself didn't set the example for others who modify
the code to follow.

On top of that, I believe whoever modifies the code and publishes the
modification, even if just to contribute it to the FSF, is bound by
the terms of the GPL, and terefore the code modification carry the
required prominent notices.  Of course the FSF, being copyright
holder, could choose to throw them all away.

> This may possibly work when the mailing list entries exist and are
> accessible. 

True, off-line access to resources that are on-line only or even
permanently inaccessible doesn't work.  Been there, done that, it's a
pain to deal with lack of information.

-- 
Alexandre Oliva         http://www.lsd.ic.unicamp.br/~oliva/
FSF Latin America Board Member         http://www.fsfla.org/
Red Hat Compiler Engineer   aoliva@{redhat.com, gcc.gnu.org}
Free Software Evangelist  oliva@{lsd.ic.unicamp.br, gnu.org}

Re: Rant about ChangeLog entries and commit messages

[tim]

On Sun, 2007-12-02 at 21:36 +0100, Eric Botcazou wrote:
> > I'd go even further, and say if the GNU coding standards say we
> > shouldn't be putting descriptions of why we are changing things in the
> > ChangeLog, than they should be changed and should be ignored on this
> > point until they do.  Pointing to them as the if they are The One True
> > Way seems very suspect to me.  After all, how else would they ever
> > improve if nobody tries anything different?
> 
> The people who wrote them presumably thought about these issues, too.
> 

Unfortunately they didn't document the "why" just the "what"!

Tim Josling

Re: Rant about ChangeLog entries and commit messages

[Robert Dewar]

Eric Botcazou wrote:
>> I'd go even further, and say if the GNU coding standards say we
>> shouldn't be putting descriptions of why we are changing things in the
>> ChangeLog, than they should be changed and should be ignored on this
>> point until they do.  Pointing to them as the if they are The One True
>> Way seems very suspect to me.  After all, how else would they ever
>> improve if nobody tries anything different?
> 
> The people who wrote them presumably thought about these issues, too.

Maybe so, but I guess we only have a record of what they came up
with and not why :-) :-)

In the Ada revision histories, we have always given the what-and-the-why
(and if necessary the why-not), and they have proved very helpful, I 
always found the RH's for gigi (done in the gcc style, much less helpful
because they omitted the why).

Of course you have to watch out for people forgetting that RH's never
substitute for comments, but all patches are reviewed, and if that
happens it gets fixed during the review process.
> 

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> In the Ada revision histories, we have always given the what-and-the-why
> (and if necessary the why-not), and they have proved very helpful, I
> always found the RH's for gigi (done in the gcc style, much less helpful
> because they omitted the why).

Sorry, that's simply not true, the ChangeLog and the commit messages in the 
ada/ subdirectory are on par with the rest of the GCC tree, and that's fine.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> > I'd go even further, and say if the GNU coding standards say we
> > shouldn't be putting descriptions of why we are changing things in the
> > ChangeLog, than they should be changed and should be ignored on this
> > point until they do.  Pointing to them as the if they are The One True
> > Way seems very suspect to me.  After all, how else would they ever
> > improve if nobody tries anything different?
> 
> The people who wrote them presumably thought about these issues, too.

My understanding is that the concern in going the other way was in
having a ChangeLog that was too long to easy scan.  Now yes, it's true
that the concept of scanning a ChangeLog rather than a CM log quite
dated at this point, but that's GNU coding standards issue, not a GCC
issue and I don't think that trying to change that will produce much more
than heat.  I do, however, think that we have significant flexibility
in content of the svn commit message and could well decide that it's
useful to do more than echo the ChangeLog entry, but instead could include
most of the text of the patch submission message.

Re: Rant about ChangeLog entries and commit messages

[Joseph S. Myers]

On Sun, 2 Dec 2007, Daniel Berlin wrote:

> I have never, in 7 years of working on and debugging gcc, found the
> ChangeLog to be useful in debugging a problem.

I find they are useful for finding what has changed in function X (or in 
functions matching pattern Y) since 4.1, say (given a bug in 4.1-based 
sources that might be fixed by a backport of a more recent patch, which 
has been traced to involve function X in some way).

The key feature here of course is not that the logs do not contain "why", 
but that they do contain the names of all the functions changed (beyond 
purely mechanical "all callers changed" type changes) - and the function 
names can be stable even as the functions themselves move between source 
files.  I think that part of the standards remains useful with logs with 
the more detailed "why" as used in the gcc/ada/ directory.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On 12/2/07, Richard Kenner <kenner@vlsi1.ultra.nyu.edu> wrote:
> > > How could a newcomer guess why the gcc_force_collect flag needs to be
> > > reset?
> >
> > That is supposed to be written in a comment.  The change log entry
> > should describe _what_ is being changed, so that you can find out when a
> > particular change was made.
>
> Not quite.  The comments are supposed to say why the code is doing what
> it's doing (and, where it's helpful, why it ISN'T doing something else).
> Purely historical references in the comments that don't serve to clarify
> the present code are discouraged.  (We don't want comments turning in a
> blog, for example.)
>
> I view the description in the gcc-patches message as PART of the CM history
> of GCC in that IT'S the place to go to get this information.  What's
> unfortunate, I think, is that there's no easy way to find this message from
> the CM revision number.
>

Nothing stops people from putting URL's. However, I'd much rather see
us put more detailed explanations in svn log or the ChangeLog than try
to associate mailing list threads with commits.

I'm certainly not going to hunt down the URL for every thread for
every patch I commit.

Re: Rant about ChangeLog entries and commit messages

[Nicholas Nethercote]

On Sun, 2 Dec 2007, Andreas Schwab wrote:

>> | 2007-11-30  Jan Hubicka  <jh@suse.cz>
>> |
>> |         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
>> |         flag.
>>
>> How could a newcomer guess why the gcc_force_collect flag needs to be
>> reset?
>
> That is supposed to be written in a comment.

Indeed.  Some advice I once wrote:  Often I see a commit with a log message 
that lovingly explains a small change made to fix a subtle problem, but adds 
no comments to the code.  Don't do this! Put that careful description in a 
comment, where people can actually see it.  (Commit logs are basically 
invisible; even if they are auto-emailed to all developers, they are soon 
forgotten, and they don't benefit people not on the email list.)  That 
comment is not a blemish but an invaluable record of an unusual case that 
someone didn't anticipate.  If the bug-fix was pre-empted by a lengthy email 
exchange, include some or all of that exchange if it helps.

Nick

Re: Rant about ChangeLog entries and commit messages

[Andreas Schwab]

Nicholas Nethercote <njn@csse.unimelb.edu.au> writes:

> On Sun, 2 Dec 2007, Andreas Schwab wrote:
>
>>> | 2007-11-30  Jan Hubicka  <jh@suse.cz>
>>> |
>>> |         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
>>> |         flag.
>>>
>>> How could a newcomer guess why the gcc_force_collect flag needs to be
>>> reset?
>>
>> That is supposed to be written in a comment.
>
> Indeed.  Some advice I once wrote:  Often I see a commit with a log
> message that lovingly explains a small change made to fix a subtle
> problem, but adds no comments to the code.  Don't do this! Put that
> careful description in a comment, where people can actually see it.
> (Commit logs are basically invisible; even if they are auto-emailed to all
> developers, they are soon forgotten, and they don't benefit people not on
> the email list.)

Moreover, if you later look at a commit log you don't know whether it
still describes the current code, you have to carefully inspect the
later history whether there were any further refinements, for example.
A comment will be updated over time and is always (supposed to be) on
par with the code.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> I tend to find GCC ChangeLog entries useless. For example, the more
>
> recent ChangeLog entry in gcc/ChangeLog is:
> | 2007-11-30  Jan Hubicka  <jh@suse.cz>
> |
> |         * ggc-common.c (dump_ggc_loc_statistics): Reset ggc_force_collect
> |         flag.
>
> How could a newcomer guess why the gcc_force_collect flag needs to be
> reset?

He indeed cannot, but the ChangeLog is not meant to make it possible either.
See http://gcc.gnu.org/contribute.html, especially the GNU Coding Standards.

> Jan posted a useful explanation on gcc-patches, but finding it 
> by searching the mailing-list is not practical and it is not coupled
> with the checkin.

That's how it has always worked so it should be more or less practical.
For PRs, there is a link (URL: field), maybe we should use PRs more often.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu]

On  2/12, Eric Botcazou wrote:

| He indeed cannot, but the ChangeLog is not meant to make it possible either.
| See http://gcc.gnu.org/contribute.html, especially the GNU Coding Standards.

I know this document and I think the part on ChangeLog doesn't achieve
its purpose:

http://www.gnu.org/prep/standards/standards.html#Change-Logs

   Keep a change log to describe all the changes made to program source
   files. The purpose of this is so that people investigating bugs in the
   future will know about the changes that might have introduced the bug.
   Often a new bug can be found by looking at what was recently changed.
   More importantly, change logs can help you eliminate conceptual
   inconsistencies between different parts of a program, by giving you a
   history of how the conflicting concepts arose and who they came from.

This is precisely why I am proposing an evolution in the current
process.

Also, this document states:

   There's no need to describe the full purpose of the changes or how
   they work together. If you think that a change calls for explanation,
   you're probably right. Please do explain it—but please put the
   explanation in comments in the code, where people will see it whenever
   they see the code.

When you fix a bug by changing a constant (for example if there has been
an offset by one error or, as I did a few minutes ago in
config/sh/sh.md, there was an error in the argument to consider), this
doesn't always mandate a comment in the code. For example, I think a
description such as the one I wrote when describing the problem

   cmpgeusi_t splitting code compares operand 0 to 0, while this constant
   value can only be in operand 1. When compiling the Ada runtime, this
   leads to a "cmp/hs #0,r7" instruction which is not valid as "cmp/hs"
   operands must be two registers.

along with the above change would have been a better commit message than
just

    gcc/
        * config/sh/sh.md (cmpgeusi_t): Fix condition.

which I used as suggested.

| That's how it has always worked so it should be more or less practical.

Sure, it works. But this is not a reason not to improve the process.

| For PRs, there is a link (URL: field), maybe we should use PRs more often.

This field is useful to look at the discussion that led to the change,
but PRs often contain no synthetic information on the analysis of the
problem unless when the PR submitter sends a patch himself (in which
case he often includes his analysis to get a better chance to get his
patch checked in).

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> I know this document and I think the part on ChangeLog doesn't achieve
> its purpose:
>
> http://www.gnu.org/prep/standards/standards.html#Change-Logs
>
>    Keep a change log to describe all the changes made to program source
>    files. The purpose of this is so that people investigating bugs in the
>    future will know about the changes that might have introduced the bug.
>    Often a new bug can be found by looking at what was recently changed.
>    More importantly, change logs can help you eliminate conceptual
>    inconsistencies between different parts of a program, by giving you a
>    history of how the conflicting concepts arose and who they came from.

Could you elaborate?

> When you fix a bug by changing a constant (for example if there has been
> an offset by one error or, as I did a few minutes ago in
> config/sh/sh.md, there was an error in the argument to consider), this
> doesn't always mandate a comment in the code. For example, I think a
> description such as the one I wrote when describing the problem
>
>    cmpgeusi_t splitting code compares operand 0 to 0, while this constant
>    value can only be in operand 1. When compiling the Ada runtime, this
>    leads to a "cmp/hs #0,r7" instruction which is not valid as "cmp/hs"
>    operands must be two registers.
>
> along with the above change would have been a better commit message than
> just
>
>     gcc/
>         * config/sh/sh.md (cmpgeusi_t): Fix condition.
>
> which I used as suggested.

Not really in my opinion, it's a trivial fix and totally unrelated to Ada in 
itself, "Fix typo" or "Fix obvious mistake" would have been just fine too.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu]

On  2/12, Eric Botcazou wrote:

| > I know this document and I think the part on ChangeLog doesn't achieve
| > its purpose:
| >
| > http://www.gnu.org/prep/standards/standards.html#Change-Logs
| >
| >    Keep a change log to describe all the changes made to program source
| >    files. The purpose of this is so that people investigating bugs in the
| >    future will know about the changes that might have introduced the bug.
| >    Often a new bug can be found by looking at what was recently changed.
| >    More importantly, change logs can help you eliminate conceptual
| >    inconsistencies between different parts of a program, by giving you a
| >    history of how the conflicting concepts arose and who they came from.
| 
| Could you elaborate?

I'll take an example from one of your recent changes in gcc/ChangeLog:

   2007-11-19  Eric Botcazou  <ebotcazou@adacore.com>

           * stor-layout.c (lang_adjust_rli): Delete.
           (set_lang_adjust_rli): Likewise.
           (layout_type): Do not call lang_adjust_rli hook.
           * tree.h (set_lang_adjust_rli): Delete.

Without digging in the mailing-list archives to see why you made the
change, if something new breaks on a STABS platform I will have no hint
that this change was in any way related to STABS.

If we didn't use ChangeLogs and if commit logs contained the information
you gave on the mailing-list, this would be much easier:

   The compiler has been broken on STABS platform since mapped locations
   were enabled by default.  The Ada front-end is emitting debug info too
   early.  The patch also reorganizes a little the front-end's initialization
   and gets rid of dead code in the process, which in turn enables a further
   cleanup in the middle-end.

Also note that the ChangeLog doesn't give any hint that changes in the
ada directory have been made at the same time, only "svn log" reveals
that. So far for the "The purpose of this is so that people investigating
bugs in the future will know about the changes that might have introduced
the bug." sentence.

I would prefer that information which is deemed necessary for
peer-review when a patch is sent to gcc-patches@ is also included in
GCC log history.

| > [sh.md fix]
|
| Not really in my opinion, it's a trivial fix and totally unrelated to Ada in 
| itself, "Fix typo" or "Fix obvious mistake" would have been just fine too.

Well, I find it useful to know which part of the compiler has exercized
this code path (as obviously there was no test associated with this
optimization) and uncovered the bug, but I agree that this was an obvious
typo fix.

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> I'll take an example from one of your recent changes in gcc/ChangeLog:
>
>    2007-11-19  Eric Botcazou  <ebotcazou@adacore.com>
>
>            * stor-layout.c (lang_adjust_rli): Delete.
>            (set_lang_adjust_rli): Likewise.
>            (layout_type): Do not call lang_adjust_rli hook.
>            * tree.h (set_lang_adjust_rli): Delete.
>
> Without digging in the mailing-list archives to see why you made the
> change, if something new breaks on a STABS platform I will have no hint
> that this change was in any way related to STABS.

But this change has nothing to do with STABS. :-)

> Also note that the ChangeLog doesn't give any hint that changes in the
> ada directory have been made at the same time, only "svn log" reveals
> that. So far for the "The purpose of this is so that people investigating
> bugs in the future will know about the changes that might have introduced
> the bug." sentence.

Well, any changes in the compiler can potentially introduce bugs elsewhere and 
I suppose that you aren't proposing to mention all the known dependencies in 
the commit message.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Samuel Tardieu]

>>>>> "Eric" == Eric Botcazou <ebotcazou@libertysurf.fr> writes:

>> Without digging in the mailing-list archives to see why you made
>> the change, if something new breaks on a STABS platform I will have
>> no hint that this change was in any way related to STABS.

Eric> But this change has nothing to do with STABS. :-)

Sure, but as you explained yourself in the message I cited, the reason
to do this change was because of a problem in STABS info generation :)

Eric> Well, any changes in the compiler can potentially introduce bugs
Eric> elsewhere and I suppose that you aren't proposing to mention all
Eric> the known dependencies in the commit message.

Of course not, but when such a dependency is the reason you make a
change in the first place, I think it ought to be mentionned. If the
chance caused a regression on an obscure platform using some barely
used debugging format, this could give a hint of where to look (STABS
for example) to see how it is done there and if bogus assumptions were
made about the previous behaviour.

  Sam
-- 
Samuel Tardieu -- sam@rfc1149.net -- http://www.rfc1149.net/

Re: Rant about ChangeLog entries and commit messages

[Eric Botcazou]

> Sure, but as you explained yourself in the message I cited, the reason
> to do this change was because of a problem in STABS info generation :)

"reason" is not quite appropriate in this case, "occasion" is more accurate.

-- 
Eric Botcazou

Re: Rant about ChangeLog entries and commit messages

[Ben Elliston]

> This *is* the information I would expect to be present somewhere in
> GCC history. A clear and detailed information on why the change was
> necessary. Sure, in some case the checkin references a PR, but the PR
> often contains information of what didn't work before the change and
> the same information which is already repeated three times (ChangeLog,
> svn log and svn diff).

Keep in mind that the GNU coding standard introduced ChangeLogs before
networked version control systems.  In those days, you would receive a
GCC release tarball with a ChangeLog.  There was no way to do "svn log"
or "svn diff" operations.

Even in recent years, I have worked on GCC trees that were exported from
the version control systems of other companies and that I did not have
access to.  In these situations, ChangeLogs are quite a bit more
valuable.

Having said that, I find the lack of rationale for some changes to be a
bit irritating.  I know that this should be done through code comments,
but those are often made across the changeset and in different files.
There is rarely a single summary of the need for the change.  It would
be nice to consider a practice similar to that used by NetBSD, which is
to use a paragraph or so describing the need for the change (similar to
what we do when we introduce a patch on gcc-patches) and inserting that
comment into the svn commit message.

Ben

Re: Rant about ChangeLog entries and commit messages

[Daniel Jacobowitz]

On Mon, Dec 03, 2007 at 10:02:13AM +1100, Ben Elliston wrote:
> Having said that, I find the lack of rationale for some changes to be a
> bit irritating.  I know that this should be done through code comments,
> but those are often made across the changeset and in different files.
> There is rarely a single summary of the need for the change.  It would
> be nice to consider a practice similar to that used by NetBSD, which is
> to use a paragraph or so describing the need for the change (similar to
> what we do when we introduce a patch on gcc-patches) and inserting that
> comment into the svn commit message.

Or even into the ChangeLog...

I've worked on other projects that did this.  I found it incredibly
helpful.

-- 
Daniel Jacobowitz
CodeSourcery

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> Having said that, I find the lack of rationale for some changes to be a
> bit irritating.  I know that this should be done through code comments,
> but those are often made across the changeset and in different files.

And it's often not appropriate to put the reason (or even nature) of the
change in comments because you run the risk of creating what is essentially
a useless monologue to somebody trying to understand the present code:

	/* Extract the two operands of the expression.  Note that at one point
	   this code had a typo and extracted the same operand twice.
	   Paul tried to fix it on February 10, 1997, but actually
	   introduced another bug where it again extracted the same operand
	   twice, but this time the other operand.  Jeff finally got it
	   right on February 12, 1997 and that's the present code.  */
	op0 = TREE_OPERAND (t, 0);
	op1 = TREE_OPERAND (t, 1);

That's not very useful!

Re: Rant about ChangeLog entries and commit messages

[Diego Novillo]

On 12/02/07 05:05, Samuel Tardieu wrote:

> Maybe we should consider dropping ChangeLogs and using better checkin
> messages.

I'm not sure people will want to drop ChangeLogs anytime soon.  I don't 
find them all that useful, but I *have* used them extensively when doing 
archeology.  It gives you the initial thread to pull when finding out 
about changes.

What I *do* miss a lot is a an easier way to link from the ChangeLog 
entry into the email message explaining the whys and hows of a change. 
In this respect, the comment in the code is not enough.  The comment 
explains what the code does today, it does not (and should not) explain 
the history of that piece of code.  Otherwise, comments would soon grow 
to useless proportions.

The history is something one finds on the mailing lists.  So, my 
proposal is to add a commit-time check that makes sure that the commit 
message contains a URL to the message describing the change.  IIUC, such 
check shouldn't be hard to implement (Dan?)

I try to do that with fixed PRs.  When closing one, I usually add a link 
to the message explaining the fix.

The only annoying issue with this proposal is that it forces the 
committer to fish out the message URL from the mailing lists, so perhaps 
we could make the check a warning instead of an error.

Thoughts?


Diego.

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> I'm not sure people will want to drop ChangeLogs anytime soon.  I don't 
> find them all that useful, but I *have* used them extensively when doing 
> archeology.  It gives you the initial thread to pull when finding out 
> about changes.
> 
> What I *do* miss a lot is a an easier way to link from the ChangeLog 
> entry into the email message explaining the whys and hows of a change. 
> In this respect, the comment in the code is not enough.  The comment 
> explains what the code does today, it does not (and should not) explain 
> the history of that piece of code.  Otherwise, comments would soon grow 
> to useless proportions.

I agree completely with all of that.

Re: Rant about ChangeLog entries and commit messages

[Bernd Schmidt]

Diego Novillo wrote:
> The history is something one finds on the mailing lists.  So, my
> proposal is to add a commit-time check that makes sure that the commit
> message contains a URL to the message describing the change.  IIUC, such
> check shouldn't be hard to implement (Dan?)

I'd much prefer the text from the mail message be repeated in the commit
log.  Removes one step of indirection both when writing and reading the log.

Of course, that way it's not something that can easily be enforced
automatically.


Bernd
-- 
This footer brought to you by insane German lawmakers.
Analog Devices GmbH      Wilhelm-Wagenfeld-Str. 6      80807 Muenchen
Sitz der Gesellschaft Muenchen, Registergericht Muenchen HRB 40368
Geschaeftsfuehrer Thomas Wessel, William A. Martin, Margaret Seif

Re: Rant about ChangeLog entries and commit messages

[Ian Lance Taylor]

Bernd Schmidt <bernds_cb1@t-online.de> writes:

> Diego Novillo wrote:
> > The history is something one finds on the mailing lists.  So, my
> > proposal is to add a commit-time check that makes sure that the commit
> > message contains a URL to the message describing the change.  IIUC, such
> > check shouldn't be hard to implement (Dan?)
> 
> I'd much prefer the text from the mail message be repeated in the commit
> log.  Removes one step of indirection both when writing and reading the log.
> 
> Of course, that way it's not something that can easily be enforced
> automatically.

I would find the URL to be very useful, because it links to the
discussion.  Reasonably often the last e-mail message is something
like "Does this version look OK?"

Ian

Re: Rant about ChangeLog entries and commit messages

[Diego Novillo]

Bernd Schmidt wrote:

> I'd much prefer the text from the mail message be repeated in the commit
> log.  Removes one step of indirection both when writing and reading the log.

I guess that could work, but that wouldn't give a way into the history 
for the change.  Several times there is a post-mortem discussion on the 
patch, leading to more patches.


Diego.

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> I guess that could work, but that wouldn't give a way into the history 
> for the change.  Several times there is a post-mortem discussion on the 
> patch, leading to more patches.

How about both?

Re: Rant about ChangeLog entries and commit messages

[Diego Novillo]

On 12/03/07 13:50, Richard Kenner wrote:
>> I guess that could work, but that wouldn't give a way into the history 
>> for the change.  Several times there is a post-mortem discussion on the 
>> patch, leading to more patches.
> 
> How about both?

Sure.


Diego.

Re: Rant about ChangeLog entries and commit messages

[Tim Josling]

On Mon, 2007-12-03 at 13:58 -0500, Diego Novillo wrote:
> On 12/03/07 13:50, Richard Kenner wrote:
> >> I guess that could work, but that wouldn't give a way into the history 
> >> for the change.  Several times there is a post-mortem discussion on the 
> >> patch, leading to more patches.
> > 
> > How about both?
> 
> Sure.
> 
> 
> Diego.

Quite a few people are worried about verbose descriptions of changes
cluttering up the ChangeLog. Others (like me) would like a way easily to
find the discussions about the change, and would like a brief indication
in the ChangeLog of the context of the change. The FSF also has good
reasons for keeping solid records of who made what change.

So, how about this:

1. For a PR fix, continue to record the PR number and category.
Like this: 
      PR tree-optimization/32694

2. For all changes, a one-line record giving the context, plus the URL
of a key message in the email message trail, unless the intent is
plainly obvious such as bumping the version number.
Like this:
      Gimplification of Fortran front end. 
      http://gcc.gnu.org/ml/gcc-patches/2007-12/msg00072.html       

3. Continue to record "who made what change".
Like this: 
       * config/xtensa/xtensa.c (xtensa_expand_prologue): Put a
REG_FRAME_RELATED_EXPR note on the last insn that sets up the stack
pointer or frame pointer.

This should satisfy everyone's needs.

This would by no means be the largest divergence from the FSF standards
by the GCC project. The use of languages other than C in the Ada front
end is non-compliant by my reading. The compliance of the rest of the
code to the FSF standards is spotty at times eg the garbage collection
code.

While this is a divergence from the FSF standards, it is a positive
change and no information is being lost.

It would be interesting to ask someone who was around at the time why
the guidelines were written as they were. They rationale may no longer
be relevant.

Tim Josling

Re: Rant about ChangeLog entries and commit messages

[Richard Kenner]

> I'd much prefer the text from the mail message be repeated in the commit
> log.  Removes one step of indirection both when writing and reading the log.

I would as well.  Especially if you're trying to scan a large part of
the log looking for something.  

Re: Rant about ChangeLog entries and commit messages

[Tom Tromey]

>>>>> "Diego" == Diego Novillo <dnovillo@google.com> writes:

Diego> I'm not sure people will want to drop ChangeLogs anytime soon.  I
Diego> don't find them all that useful, but I *have* used them extensively
Diego> when doing archeology.  It gives you the initial thread to pull when
Diego> finding out about changes.

Yeah.  They aren't incredibly useful, but they aren't useless, either.

One thing they give you that 'svn annotate' does not is a record of
when things were deleted.  I use them this way on occasion.

I have a few concerns about a change in this area.

First, continuing to have good quality messages.  Right now at the
very least you get a (semi-) accurate record of what was touched.
I've seen plenty of ChangeLog-less projects out there than end up with
commits like "fixed a bug", or even worse.

I suppose we'll need to review the commit messages just like we review
ChangeLog entries now.  That doesn't sound fun, but I suppose it won't
be too much work.

Second, whether it makes the process heavier:

Diego> The only annoying issue with this proposal is that it forces the
Diego> committer to fish out the message URL from the mailing lists, so
Diego> perhaps we could make the check a warning instead of an error.

This would be a big pain.  Perhaps it wouldn't be so bad if the mail
server added a URL to the header somewhere, so I could wait for the
mail to come back and then look it up.  The obvious alternative of
hitting reload on the gcc web page is unattractive.

Also it seems to me that this will make it a bit harder for developers
without write access to get their patches checked in ... because it
will mean even more work for whoever does the commit.

Tom

Re: Rant about ChangeLog entries and commit messages

[Ben Elliston]

On Tue, 2007-12-04 at 09:18 -0700, Tom Tromey wrote:

> First, continuing to have good quality messages.  Right now at the
> very least you get a (semi-) accurate record of what was touched.
> I've seen plenty of ChangeLog-less projects out there than end up with
> commits like "fixed a bug", or even worse.

Something else that hasn't been raised is that ChangeLogs can be
revised.  We often see people making mistakes with their ChangeLog
entries, but since the ChangeLog is versioned, they can revise it.  If
you screw up a commit message, it's much harder to fix it (and a purist
might argue that to do so would be destroying revision history).

> Also it seems to me that this will make it a bit harder for developers
> without write access to get their patches checked in ... because it
> will mean even more work for whoever does the commit.

That's a good point.

Ben

Re: Rant about ChangeLog entries and commit messages

[Daniel Berlin]

On Dec 5, 2007 6:15 PM, Ben Elliston <bje@au1.ibm.com> wrote:
> On Tue, 2007-12-04 at 09:18 -0700, Tom Tromey wrote:
>
> > First, continuing to have good quality messages.  Right now at the
> > very least you get a (semi-) accurate record of what was touched.
> > I've seen plenty of ChangeLog-less projects out there than end up with
> > commits like "fixed a bug", or even worse.
>
> Something else that hasn't been raised is that ChangeLogs can be
> revised.  We often see people making mistakes with their ChangeLog
> entries, but since the ChangeLog is versioned, they can revise it.  If
> you screw up a commit message, it's much harder to fix it (and a purist
> might argue that to do so would be destroying revision history).
Uh?


svn propedit --revision <rev number> svn:log

Hope this helps!

Re: Rant about ChangeLog entries and commit messages

[Ben Elliston]

On Wed, 2007-12-05 at 18:35 -0500, Daniel Berlin wrote:

> svn propedit --revision <rev number> svn:log

OK, well, it used to be a bit trickier in CVS .. :-)

Ben

Re: Rant about ChangeLog entries and commit messages

[Andreas Schwab]

Ben Elliston <bje@au1.ibm.com> writes:

> On Wed, 2007-12-05 at 18:35 -0500, Daniel Berlin wrote:
>
>> svn propedit --revision <rev number> svn:log
>
> OK, well, it used to be a bit trickier in CVS .. :-)

In CVS it's just a cvs admin -m as well.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Rant about ChangeLog entries and commit messages

[Robert Dewar]

Ben Elliston wrote:

> Something else that hasn't been raised is that ChangeLogs can be
> revised.  We often see people making mistakes with their ChangeLog
> entries, but since the ChangeLog is versioned, they can revise it.  If
> you screw up a commit message, it's much harder to fix it (and a purist
> might argue that to do so would be destroying revision history).

What we do with Ada is to allow *additions* to an existing revision
history entry, but not modifications of what is already there.