* 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 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 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: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
* 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
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).