Updated HACKING

Updated HACKING

[Han-Wen Nienhuys]

Please check dev/hanwen for changes.  

I've also looked at renaming ChangeLogs, but I got a scare when I saw how 
many we have (I forgot GUILE did per directory ones).  Seeing so many deprecated
files makes want to

- delete them, or
- put them in a separate subdirectory where they will be out of sight.  

comments?


-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Updated HACKING

[Ludovic Courtès]

Hi,

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> Please check dev/hanwen for changes.  

The `HACKING' changes looks good overall, thank you!  The "complete
description in the commit message" should rather be "complete
ChangeLog-style description in the commit message (see the GNU Coding
Standards for details)".  The sentence "Post your patch to
guile-devel@gnu.org" lacks a period.

(It was funny to see notes about EGCS, a patch for CVS, etc.  ;-))

> I've also looked at renaming ChangeLogs, but I got a scare when I saw how 
> many we have (I forgot GUILE did per directory ones).  Seeing so many deprecated
> files makes want to
>
> - delete them, or

No.

> - put them in a separate subdirectory where they will be out of sight.  

Not sure.  How about just renaming them to `ChangeLog-2008' for now, and
add a top-level `ChangeLog' that reads something like "Please refer to
git.sv.gnu.org blah blah blah"?

Thanks,
Ludo'.

Re: Updated HACKING

[Han-Wen Nienhuys]

Ludovic Courtès escreveu:
> Hi,
> 
> Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
> 
>> Please check dev/hanwen for changes.  
> 
> The `HACKING' changes looks good overall, thank you!  The "complete
> description in the commit message" should rather be "complete
> ChangeLog-style description in the commit message (see the GNU Coding
> Standards for details)".  The sentence "Post your patch to
> guile-devel@gnu.org" lacks a period.

How about the following:


- Provide a description in the commit message, like so:

  1-line description of change

  More extensive discussion of your change.  Document why you are
  changing things.

  * filename (function name): file specific change comments.


This the 1 line + more extensive doc is the standard for git (AFAIK) 
and lilypond. Background info is very useful for later referral.  

I would like to propose to only have the 

 * filename

sections if there are file specific notes that are not covered by
the general description and git's list of modified files.

-- 
 Han-Wen Nienhuys - hanwen@xs4all.nl - http://www.xs4all.nl/~hanwen

Re: Updated HACKING

[Ludovic Courtès]

Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> How about the following:

Guile is a GNU project, let's stick to the good old and widely
understood ChangeLog style rather than rolling our own format.

Thanks,
Ludo'.

Re: Updated HACKING

[Andy Wingo]

On Wed 03 Sep 2008 19:35, Han-Wen Nienhuys <hanwen@xs4all.nl> writes:

> How about the following:
>
>
> - Provide a description in the commit message, like so:
>
>   1-line description of change
>
>   More extensive discussion of your change.  Document why you are
>   changing things.
>
>   * filename (function name): file specific change comments.

This looks really good to me. If we move from ChangeLogs, then it makes
sense to adjust the format as necessary, preserving the same semantics.
We should probably propose this as the standard GNU format, actually. (I
believe bzr people use something like this as well.)

> I would like to propose to only have the 
>
>  * filename
>
> sections if there are file specific notes that are not covered by
> the general description and git's list of modified files.

I agree in the case that e.g. you're just updating copyrights; but
generally I prefer to have the files in. It's nice to be able to read
everything in one place, instead of bouncing my eye around in gitk, and
it doesn't impact readability adversely since it's after any general
comment.

Also, listing files helps the committer make sure that you're committing
only those files that you intend to -- often, when I make the commit
message, I find that there's some unwanted change, which reminds me to
exclude it from the commit.

Andy
-- 
http://wingolog.org/

Re: Updated HACKING

[Ludovic Courtès]

Hi,

Andy Wingo <wingo@pobox.com> writes:

> On Wed 03 Sep 2008 19:35, Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>
>> How about the following:
>>
>>
>> - Provide a description in the commit message, like so:
>>
>>   1-line description of change
>>
>>   More extensive discussion of your change.  Document why you are
>>   changing things.
>>
>>   * filename (function name): file specific change comments.
>
> This looks really good to me. If we move from ChangeLogs, then it makes
> sense to adjust the format as necessary, preserving the same semantics.
> We should probably propose this as the standard GNU format, actually. (I
> believe bzr people use something like this as well.)

Actually, what you're proposing is what I had in mind.  :-)

It's essentially the GNU ChangeLog format, with the addition of the
summary line and optional extended summary.  Adding a one-line summary
has been common practice in some projects, there are examples in Gnulib
and Guile.

Anyway, if you are willing to propose something beyond just that, the
discussion should be directed to `gnu-prog-discuss' IMO.

Thanks,
Ludo'.

Re: Updated HACKING

[Neil Jerram]

2008/9/4 Ludovic Courtès <ludo@gnu.org>:
> Hi,
>
> Andy Wingo <wingo@pobox.com> writes:
>
>> On Wed 03 Sep 2008 19:35, Han-Wen Nienhuys <hanwen@xs4all.nl> writes:
>>
>>> How about the following:
>>>
>>>
>>> - Provide a description in the commit message, like so:
>>>
>>>   1-line description of change
>>>
>>>   More extensive discussion of your change.  Document why you are
>>>   changing things.
>>>
>>>   * filename (function name): file specific change comments.
>>
>> This looks really good to me. If we move from ChangeLogs, then it makes
>> sense to adjust the format as necessary, preserving the same semantics.
>> We should probably propose this as the standard GNU format, actually. (I
>> believe bzr people use something like this as well.)
>
> Actually, what you're proposing is what I had in mind.  :-)
>
> It's essentially the GNU ChangeLog format, with the addition of the
> summary line and optional extended summary.  Adding a one-line summary
> has been common practice in some projects, there are examples in Gnulib
> and Guile.

For the record, I'm happy with this too.  Thanks Han-Wen for
describing this in HACKING (and for the other updates).

So, have we yet announced that we're definitively switching from
ChangeLog change logs to Git commit message change logs?  In case
anyone's in doubt: we are.

In practice, I believe the last commit with a ChangeLog change was
31st August, so for the record (if needed) we can say that the switch
happened from 1st September onwards.

Regards,
      Neil

Re: Updated HACKING

[Ludovic Courtès]

Hi,

"Neil Jerram" <neiljerram@googlemail.com> writes:

> In practice, I believe the last commit with a ChangeLog change was
> 31st August, so for the record (if needed) we can say that the switch
> happened from 1st September onwards.

Yes, I forgot to rename the ChangeLog files, etc., but I can do it later
on today or this week-end if nobody else does.

Thanks,
Ludo'.

`ChangeLog' files are gone!

[Ludovic Courtès]

Hello!

"Neil Jerram" <neiljerram@googlemail.com> writes:

> In practice, I believe the last commit with a ChangeLog change was
> 31st August, so for the record (if needed) we can say that the switch
> happened from 1st September onwards.

I committed two things: renaming the `ChangeLog' files to
`ChangeLog-2008', and adding them to the distribution.  The first commit
also adds an explanation in the top-level `ChangeLog' file.  Feel free
to amend it if you think of improvements.

Thanks,
Ludo'.

Re: `ChangeLog' files are gone!

[Neil Jerram]

2008/9/12 Ludovic Courtès <ludo@gnu.org>:

> I committed two things: renaming the `ChangeLog' files to
> `ChangeLog-2008', and adding them to the distribution.  The first commit
> also adds an explanation in the top-level `ChangeLog' file.  Feel free
> to amend it if you think of improvements.

All looks perfect!

    Neil