Re: ChangeLog?

Re: ChangeLog?

[Robert J. Chassell]

You make a good point that not everyone uses CVS, so ChangeLogs
produced by CVS are not so good.

    _All_ code changes (maybe not comment and doc changes) should have
    entries in the [big] ChangeLog file.

This means we need to change the Emacs Manual.  Currently,

        (emacs)Types of Log File
says

    When you use version control, you can use just the per-file log if
    you wish, or you can use both kinds of logs.  ...

This could be restated as

        emacs/man/files.texi   
        Types of Log File

    When you use a version control system that provides a per-file
    log, you should use @strong{both} the the per-file log and the
    more general @file{ChangeLog}.  This is because it is inconvenient
    or impossible for someone using a different version control system
    to access another version control system's per-file log.  This
    policy is different from the past, when you recorded small changes
    in the per-file log only.

    Typically you want to write just one entry for each change.  You
    can write the entry in @file{ChangeLog}, using the @kbd{C-x 4 a}
    command (@pxref{Change Log}), and then copy it to the log buffer
    when you check in the change.  Or you can write the entry in the
    log buffer while checking in the change, using the @kbd{C-x v v}
    command, and later use the @kbd{C-x v a} command to copy it to the
    more general @file{ChangeLog} (@pxref{Change Logs and VC}).

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: ChangeLog?

[Stefan Monnier]

>     When you use a version control system that provides a per-file
>     log, you should use @strong{both} the the per-file log and the
>     more general @file{ChangeLog}.  This is because it is inconvenient
>     or impossible for someone using a different version control system
>     to access another version control system's per-file log.  This
>     policy is different from the past, when you recorded small changes
>     in the per-file log only.

>     Typically you want to write just one entry for each change.  You
>     can write the entry in @file{ChangeLog}, using the @kbd{C-x 4 a}
>     command (@pxref{Change Log}), and then copy it to the log buffer
>     when you check in the change.  Or you can write the entry in the
>     log buffer while checking in the change, using the @kbd{C-x v v}
>     command, and later use the @kbd{C-x v a} command to copy it to the
>     more general @file{ChangeLog} (@pxref{Change Logs and VC}).

This is all highly dependent on the specific situation.  E.g. it depends on
the revision control system in use and lots of other things.  E.g. many
revision control systems provide special facilities to automatically
maintain an explicit changelog-like file (even RCS and CVS provide something
like that with their $Log$ keyword).

Depending on the specific circumstance it can be preferable to use
a manually managed ChangeLog file (this is usually the case with RCS and
CVS, AFAIK), but with systems like Subversion and Arch it's usually not
worth the trouble.


        Stefan

Re: ChangeLog?

[Kim F. Storm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Depending on the specific circumstance it can be preferable to use
> a manually managed ChangeLog file (this is usually the case with RCS and
> CVS, AFAIK), but with systems like Subversion and Arch it's usually not
> worth the trouble.

Can Subversion and arch create a ChangeLog(-like) file for inclusion in
a release tar-ball?

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: ChangeLog?

[Stefan Monnier]

>> Depending on the specific circumstance it can be preferable to use
>> a manually managed ChangeLog file (this is usually the case with RCS and
>> CVS, AFAIK), but with systems like Subversion and Arch it's usually not
>> worth the trouble.

> Can Subversion and arch create a ChangeLog(-like) file for inclusion in
> a release tar-ball?

Yes.  Actually CVS as well with cvs2cl.


        Stefan

Re: ChangeLog?

[Richard Stallman]

    You make a good point that not everyone uses CVS, so ChangeLogs
    produced by CVS are not so good.

What is the question you are discussing?
What change was proposed?  What does someone claim is an error?

Re: ChangeLog?

[Miles Bader]

On Wed, 02 Mar 2005 21:27:47 -0500, Richard Stallman <rms@gnu.org> wrote:
>     You make a good point that not everyone uses CVS, so ChangeLogs
>     produced by CVS are not so good.
> 
> What is the question you are discussing?
> What change was proposed?  What does someone claim is an error?

Bob made a (small) code change, and described it in the CVS log, but
didn't add a ChangeLog entry.  I asked him to make a ChangeLog entry,
and gave my opinion that CVS log entries are not sufficient for
bug-tracking purposes (for any code change).  From his reply, I gather
than the documentation contradicts this position.

-Miles
-- 
Do not taunt Happy Fun Ball.

Re: ChangeLog?

[Richard Stallman]

      From his reply, I gather
    than the documentation contradicts this position.

No, it doesn't.  That was a misunderstanding.

The Emacs manual describes multiple approaches for maintaining a
project.  Each project, however, has its own specific policies.  In
Emacs, the approach we use is that all changes are listed in
ChangeLog.

Bob, would you please put your change in ChangeLog?

Re: ChangeLog?

[Robert J. Chassell]

        I gather the documentation contradicts this position.

    No, it doesn't.  That was a misunderstanding.

    In Emacs, the approach we use is that all changes are listed in
    ChangeLog.

Which ChangeLog?  The Emacs CVS offers two ChangeLogs and in
    (emacs)Types of Log File
the Emacs manual says

    When you use version control, you can use just the per-file log if
    you wish, or you can use both kinds of logs.  ...

So I originally used the smaller, per-file ChangeLog.  Miles persuaded
me to add a comment to the larger ChangeLog, which I did.

Shall I change the documentation as I suggested to:

        emacs/man/files.texi   
        Types of Log File

    When you use a version control system that provides a per-file
    log, you should use @strong{both} the the per-file log and the
    more general @file{ChangeLog}.  This is because it is inconvenient
    or impossible for someone using a different version control system
    to access another version control system's per-file log.  This
    policy is different from the past, when you recorded small changes
    in the per-file log only.

    Typically you want to write just one entry for each change.  You
    can write the entry in @file{ChangeLog}, using the @kbd{C-x 4 a}
    command (@pxref{Change Log}), and then copy it to the log buffer
    when you check in the change.  Or you can write the entry in the
    log buffer while checking in the change, using the @kbd{C-x v v}
    command, and later use the @kbd{C-x v a} command to copy it to the
    more general @file{ChangeLog} (@pxref{Change Logs and VC}).

My hunch is that the current documentation is different than you
thought and that the changed documentation says what you mean.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: ChangeLog?

[Luc Teirlinck]

Robert Chassell wrote:

   Which ChangeLog?

Both.

   My hunch is that the current documentation is different than you
   thought and that the changed documentation says what you mean.

I do not believe so.

Richard said:

   The Emacs manual describes multiple approaches for maintaining a
   project.  Each project, however, has its own specific policies.

In other words, it is perfectly OK for other projects to just use the
per-file log.  That _definitely_ applies to individuals putting a
single file under VC.  The two logs would just duplicate each other.
The Emacs manual section on VC does _not_ attempt to describe the
specific policies _of the Emacs project_.

Sincerely,

Luc.

Re: ChangeLog?

[Miles Bader]

On Fri, 4 Mar 2005 00:41:39 +0000 (UTC), Robert J. Chassell
<bob@rattlesnake.com> wrote:
>         I gather the documentation contradicts this position.
> 
>     No, it doesn't.  That was a misunderstanding.
> 
>     In Emacs, the approach we use is that all changes are listed in
>     ChangeLog.
> 
> Which ChangeLog?  The Emacs CVS offers two ChangeLogs and in
>     (emacs)Types of Log File

The term "ChangeLog" -- note the specific capitalization -- as
generally used, has a fairly specific meaning:  it only refers to
Emacs-style ChangeLog files, not to the concept of a change log in
general.  In my experience in the free-software world, even the
specific Emacs capitalization is not necessary:  any place the term
"changelog" occurs as one word, it tends to refer to an Emacs-style
ChangeLog file.

The manual text you quote refers to "log", not "ChangeLog", when it's
talking about CVS-style logs.

> My hunch is that the current documentation is different than you
> thought and that the changed documentation says what you mean.

No, I've read the info file now, and it seems pretty explicit and
clear about the distinction between the two types of logs.

-Miles
-- 
Do not taunt Happy Fun Ball.

Re: ChangeLog?

[Nick Roberts]

 >         I gather the documentation contradicts this position.
 > 
 >     No, it doesn't.  That was a misunderstanding.
 > 
 >     In Emacs, the approach we use is that all changes are listed in
 >     ChangeLog.

That's interesting because the entry below (Types of Log File) that you wrote
(RMS) is only recorded in the CVS log.

There appear to be many files, that aren't part of the source code, that don't
get a ChangeLog entry e.g NEWS, FOR-RELEASE, documentation etc. I see no
problem with that, but I find it essential for the source code (C, lisp etc)
to understand what has caused a change in Emacs' behaviour, as I'm sure
others, who dig deeper into the code, do.

 > Which ChangeLog?  The Emacs CVS offers two ChangeLogs and in
 >     (emacs)Types of Log File
 > the Emacs manual says
 > 
 >     When you use version control, you can use just the per-file log if
 >     you wish, or you can use both kinds of logs.  ...
 > 
 > So I originally used the smaller, per-file ChangeLog.  Miles persuaded
 > me to add a comment to the larger ChangeLog, which I did.
 > 
 > Shall I change the documentation as I suggested to:
 > 
 >         emacs/man/files.texi   
 >         Types of Log File
 > 
 >     When you use a version control system that provides a per-file
 >     log, you should use @strong{both} the the per-file log and the
 >     more general @file{ChangeLog}.  This is because it is inconvenient
 >     or impossible for someone using a different version control system
 >     to access another version control system's per-file log.  This
 >     policy is different from the past, when you recorded small changes
 >     in the per-file log only.
 > 
 >     Typically you want to write just one entry for each change.  You
 >     can write the entry in @file{ChangeLog}, using the @kbd{C-x 4 a}
 >     command (@pxref{Change Log}), and then copy it to the log buffer
 >     when you check in the change.  Or you can write the entry in the
 >     log buffer while checking in the change, using the @kbd{C-x v v}
 >     command, and later use the @kbd{C-x v a} command to copy it to the
 >     more general @file{ChangeLog} (@pxref{Change Logs and VC}).

I don't even see why this node is present, let alone why it should be expanded.
This manual is meant to about Emacs, not methods of version control/change
control.


Nick

Re: ChangeLog?

[Robert J. Chassell]

Miles Bader wrote,

   ... I've read the info file now, and it seems pretty explicit and
   clear about the distinction between the two types of logs.

Yes.  I wrote that text years and years ago with wording intended to
create such a distinction.  At that time, when people referred to a
`change log', it was often difficult to determine to which of several
types of change log they refered.

I am glad to see that the distinction has taken hold and that when an
expert says `change log' (which can be written in various ways), he or
she means only the more general change log and not the per-file change
log modified by CVS.

This suggests a change in the documentation in

        emacs/man/files.texi   
        Types of Log File

that is different from what I previously suggested.  

You might want to change this proposed wording to include references
to Arch and Subversion and perhaps to other version control systems.
I do not know anything about them and and written this with that
ignorance in mind.

This new wording replaces the last paragraph of the node, the
paragraph that begins with the sentence


       When you use version control, you can use just the per-file log
    if you wish, or you can use both kinds of logs.

Here is my current sample wording:

    Some projects use several different version control systems at the
    same time, synchronizing changes among them.

    In Emacs development under CVS, the practice is to record
    @emph{all} coding changes in the more general @file{ChangeLog} but
    not changes in documentation or in the @file{NEWS} and
    @file{FOR-RELEASE} files.  Those latter changes are recorded only
    in the per-file log, a log which may be inaccessible to someone
    using a different version control system.  (Other projects may
    work differently.)

    Thus, in Emacs development when both types of log are available
    and when recording changes in code, you should use @strong{both}
    the per-file log and the more general @file{ChangeLog}

    In such a situation you typically will want to write just one
    entry for each change.  You can write the entry in
    @file{ChangeLog}, using the @kbd{C-x 4 a} command (@pxref{Change
    Log}), and then copy it to the per-file log, when that exists,
    buffer when you check in the change.  Or, when using the @kbd{C-x
    v v} command (@pxref{Log Buffer}), you can write the entry in the
    per-file log buffer while checking in the change, and later use
    the @kbd{C-x v a} command to copy it to the more general
    @file{ChangeLog} (@pxref{Change Logs and VC}).

--
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: ChangeLog?

[Richard Stallman]

	In Emacs, the approach we use is that all changes are listed in
	ChangeLog.

    Which ChangeLog?

In the ChangeLog in the directory where you made the change; or, if
there is none in that directory, in its parent directory.

	(emacs)Types of Log File
    the Emacs manual says

	When you use version control, you can use just the per-file log if
	you wish, or you can use both kinds of logs.  ...

It is describing several approaches that projects can use.  Emacs uses
the approach to list each ontrivial change both in ChangeLog and in
the file's own CVS log.

    Shall I change the documentation as I suggested to:

Please do not change it, and please let's stop discussing this.  I will
make a small change there:



  A project maintained with version control can use just the per-file
log, or it can use both kinds of logs.  It can handle some files one
way and some files the other way.  Each project has its policy, which
you should follow.

  When the policy is to use both, you typically want to write just one
entry for each change, and put the entry into both logs.  You can
write the entry in @file{ChangeLog}, then copy it to the log buffer
when you check in the change.  Or you can write the entry in the log
buffer while checking in the change, and later use the @kbd{C-x v a}
command to copy it to @file{ChangeLog} (@pxref{Change Logs and VC}).

Re: ChangeLog?

[Richard Stallman]

    That's interesting because the entry below (Types of Log File) that you wrote
    (RMS) is only recorded in the CVS log.

Until a year or two ago, we did not keep track of documentation changes
in ChangeLog.  Nowadays we do.