changeset 42327:86a0b7cc1600

Explain the difference between the per-file log maintained by the version control system and the per-directory or per-project ChangeLog.

--- a/man/files.texi	Tue Dec 25 15:30:36 2001 +0000
+++ b/man/files.texi	Tue Dec 25 15:32:10 2001 +0000
@@ -1135,6 +1135,7 @@
 @menu
 * Version Systems::  Supported version control back-end systems.
 * VC Concepts::      Words and concepts related to version control.
+* Types of Log File::    The per-file VC log in contrast to the ChangeLog.
 @end menu
 
 @node Version Systems
@@ -1219,6 +1220,54 @@
 check-in time.  However, CVS can also be set up to require locking.
 (@pxref{CVS Options}).
 
+@node Types of Log File
+@subsubsection Types of Log File
+@cindex Types of log file
+@cindex Log File, types of 
+
+GNU projects under a revision control system generally possess
+@emph{two} types of log.  These help you keep track of what goes on.
+
+One kind of log is the per-file log maintained by the revision control
+system.  This kind of log is called the @dfn{version control log}, or
+sometimes the @dfn{revision control log}, `@samp{*rcs*} log', or
+`@samp{*cvs*} log'.  The other kind of log is a per-directory or
+per-project log called the change log or @file{ChangeLog}.
+
+@cindex Version control log
+@cindex Revision control log
+@cindex Per-file log
+The per-file log is designed to tell you about each and every change
+to a file.  Each time you check in a change, you fill out a version
+control log entry.  (@xref{Log Buffer, Log Buffer, Features of the Log
+Entry Buffer}.)  Consequently, a per-file log is very detailed, with
+remarks such as `fixed typo' as well as `re-wrote from scratch'.
+
+@cindex Change log
+@cindex Per-directory log
+@cindex Per-project log 
+On the other hand, a per-directory or per-project log is intended to
+provide a chronological record of when and why you and others changed
+a program.  A @file{ChangeLog} should be moderately, but not
+excessively detailed.
+
+A single @file{ChangeLog} file can record changes for all
+the files in its directory and all its subdirectories.  A small
+program merits one @file{ChangeLog} file; a large program may well
+merit several @file{ChangeLog} file, one in each major directory.
+(@xref{Change Log, Change Log, Change Logs}.)
+
+You can use the Emacs command @r{@kbd{C-x 4 a}}
+(@code{add-change-log-entry-other-window}) to add a new entry to a
+change log file.
+
+If you use RCS or CVS, you can generate change log entries
+automatically from the version control log entries using
+the @r{@kbd{C-x v a}} (@code{vc-update-change-log}) command.
+(@xref{Change Logs and VC, Change Logs and VC, Change Logs and VC}.)
+When you do this, you will probably want to edit and shorten the
+resulting @file{ChangeLog}.
+
 @node VC Mode Line
 @subsection Version Control and the Mode Line