* Re: ChangeLog?
[not found] ` <fc339e4a05022814485fe422fb@mail.gmail.com>
@ 2005-03-01 13:29 ` Robert J. Chassell
2005-03-01 14:12 ` ChangeLog? Stefan Monnier
2005-03-03 2:27 ` ChangeLog? Richard Stallman
0 siblings, 2 replies; 14+ messages in thread
From: Robert J. Chassell @ 2005-03-01 13:29 UTC (permalink / raw
Cc: bob, emacs-devel
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-01 13:29 ` ChangeLog? Robert J. Chassell
@ 2005-03-01 14:12 ` Stefan Monnier
2005-03-01 15:06 ` ChangeLog? Kim F. Storm
2005-03-03 2:27 ` ChangeLog? Richard Stallman
1 sibling, 1 reply; 14+ messages in thread
From: Stefan Monnier @ 2005-03-01 14:12 UTC (permalink / raw
Cc: snogglethorpe, emacs-devel, miles
> 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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-01 14:12 ` ChangeLog? Stefan Monnier
@ 2005-03-01 15:06 ` Kim F. Storm
2005-03-01 16:11 ` ChangeLog? Stefan Monnier
0 siblings, 1 reply; 14+ messages in thread
From: Kim F. Storm @ 2005-03-01 15:06 UTC (permalink / raw
Cc: miles, bob, snogglethorpe, emacs-devel
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-01 15:06 ` ChangeLog? Kim F. Storm
@ 2005-03-01 16:11 ` Stefan Monnier
0 siblings, 0 replies; 14+ messages in thread
From: Stefan Monnier @ 2005-03-01 16:11 UTC (permalink / raw
Cc: bob, snogglethorpe, emacs-devel, miles
>> 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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-01 13:29 ` ChangeLog? Robert J. Chassell
2005-03-01 14:12 ` ChangeLog? Stefan Monnier
@ 2005-03-03 2:27 ` Richard Stallman
2005-03-03 3:20 ` ChangeLog? Miles Bader
1 sibling, 1 reply; 14+ messages in thread
From: Richard Stallman @ 2005-03-03 2:27 UTC (permalink / raw
Cc: bob, snogglethorpe, emacs-devel, miles
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?
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-03 2:27 ` ChangeLog? Richard Stallman
@ 2005-03-03 3:20 ` Miles Bader
2005-03-03 20:57 ` ChangeLog? Richard Stallman
0 siblings, 1 reply; 14+ messages in thread
From: Miles Bader @ 2005-03-03 3:20 UTC (permalink / raw
Cc: bob, emacs-devel, miles
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.
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-03 3:20 ` ChangeLog? Miles Bader
@ 2005-03-03 20:57 ` Richard Stallman
2005-03-04 0:41 ` ChangeLog? Robert J. Chassell
0 siblings, 1 reply; 14+ messages in thread
From: Richard Stallman @ 2005-03-03 20:57 UTC (permalink / raw
Cc: bob, emacs-devel, miles
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?
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-03 20:57 ` ChangeLog? Richard Stallman
@ 2005-03-04 0:41 ` Robert J. Chassell
2005-03-04 0:53 ` ChangeLog? Luc Teirlinck
` (3 more replies)
0 siblings, 4 replies; 14+ messages in thread
From: Robert J. Chassell @ 2005-03-04 0:41 UTC (permalink / raw
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-04 0:41 ` ChangeLog? Robert J. Chassell
@ 2005-03-04 0:53 ` Luc Teirlinck
2005-03-04 1:35 ` ChangeLog? Miles Bader
` (2 subsequent siblings)
3 siblings, 0 replies; 14+ messages in thread
From: Luc Teirlinck @ 2005-03-04 0:53 UTC (permalink / raw
Cc: rms, emacs-devel
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.
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-04 0:41 ` ChangeLog? Robert J. Chassell
2005-03-04 0:53 ` ChangeLog? Luc Teirlinck
@ 2005-03-04 1:35 ` Miles Bader
2005-03-04 13:42 ` ChangeLog? Robert J. Chassell
2005-03-04 1:49 ` ChangeLog? Nick Roberts
2005-03-04 23:46 ` ChangeLog? Richard Stallman
3 siblings, 1 reply; 14+ messages in thread
From: Miles Bader @ 2005-03-04 1:35 UTC (permalink / raw
Cc: rms, emacs-devel
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.
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-04 0:41 ` ChangeLog? Robert J. Chassell
2005-03-04 0:53 ` ChangeLog? Luc Teirlinck
2005-03-04 1:35 ` ChangeLog? Miles Bader
@ 2005-03-04 1:49 ` Nick Roberts
2005-03-04 23:46 ` ChangeLog? Richard Stallman
2005-03-04 23:46 ` ChangeLog? Richard Stallman
3 siblings, 1 reply; 14+ messages in thread
From: Nick Roberts @ 2005-03-04 1:49 UTC (permalink / raw
Cc: rms, emacs-devel
> 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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-04 1:35 ` ChangeLog? Miles Bader
@ 2005-03-04 13:42 ` Robert J. Chassell
0 siblings, 0 replies; 14+ messages in thread
From: Robert J. Chassell @ 2005-03-04 13:42 UTC (permalink / raw
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
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-04 0:41 ` ChangeLog? Robert J. Chassell
` (2 preceding siblings ...)
2005-03-04 1:49 ` ChangeLog? Nick Roberts
@ 2005-03-04 23:46 ` Richard Stallman
3 siblings, 0 replies; 14+ messages in thread
From: Richard Stallman @ 2005-03-04 23:46 UTC (permalink / raw
Cc: emacs-devel
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}).
^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: ChangeLog?
2005-03-04 1:49 ` ChangeLog? Nick Roberts
@ 2005-03-04 23:46 ` Richard Stallman
0 siblings, 0 replies; 14+ messages in thread
From: Richard Stallman @ 2005-03-04 23:46 UTC (permalink / raw
Cc: bob, emacs-devel
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.
^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2005-03-04 23:46 UTC | newest]
Thread overview: 14+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <61k6osjqsz.fsf@fencepost.gnu.org>
[not found] ` <m1D5t7c-0004QmC@rattlesnake.com>
[not found] ` <fc339e4a05022814485fe422fb@mail.gmail.com>
2005-03-01 13:29 ` ChangeLog? Robert J. Chassell
2005-03-01 14:12 ` ChangeLog? Stefan Monnier
2005-03-01 15:06 ` ChangeLog? Kim F. Storm
2005-03-01 16:11 ` ChangeLog? Stefan Monnier
2005-03-03 2:27 ` ChangeLog? Richard Stallman
2005-03-03 3:20 ` ChangeLog? Miles Bader
2005-03-03 20:57 ` ChangeLog? Richard Stallman
2005-03-04 0:41 ` ChangeLog? Robert J. Chassell
2005-03-04 0:53 ` ChangeLog? Luc Teirlinck
2005-03-04 1:35 ` ChangeLog? Miles Bader
2005-03-04 13:42 ` ChangeLog? Robert J. Chassell
2005-03-04 1:49 ` ChangeLog? Nick Roberts
2005-03-04 23:46 ` ChangeLog? Richard Stallman
2005-03-04 23:46 ` ChangeLog? Richard Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).