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.