bug#14750: [PATCH] Cleanup for "commit message"

bug#14750: [PATCH] Cleanup for "commit message"

[Xue Fuqiao]

tags patch

I found that "commit message" is not used consistently.  Maybe we should
clean this up.


=== modified file 'doc/emacs/ChangeLog'
--- doc/emacs/ChangeLog    2013-06-12 12:12:47 +0000
+++ doc/emacs/ChangeLog    2013-06-14 23:31:47 +0000
@@ -1,3 +1,11 @@
+2013-06-14  Xue Fuqiao  <xfq.free@gmail.com>
+
+    * vc1-xtra.texi (Change Logs and VC):
+    * maintaining.texi (VCS Concepts, Types of Log File)
+    (VC With A Merging VCS, VC With A Locking VCS, Log Buffer)
+    (Old Revisions, VC Change Log): Uniformize the phrasing for
+    "commit message".
+
 2013-06-11  Glenn Morris  <rgm@gnu.org>

     * maintaining.texi (VC Directory Commands): Copyedit.

=== modified file 'doc/emacs/maintaining.texi'
--- doc/emacs/maintaining.texi    2013-06-11 06:42:15 +0000
+++ doc/emacs/maintaining.texi    2013-06-14 23:31:47 +0000
@@ -51,7 +51,7 @@
 * Introduction to VC::  How version control works in general.
 * VC Mode Line::        How the mode line shows version control status.
 * Basic VC Editing::    How to edit a file under version control.
-* Log Buffer::          Features available in log entry buffers.
+* Log Buffer::          Features available in commit message buffers.
 * Registering::         Putting a file under version control.
 * Old Revisions::       Examining and comparing old versions.
 * VC Change Log::       Viewing the VC Change Log.
@@ -202,7 +202,7 @@
 @dfn{repository} which stores both the file's present state and its
 change history---enough to reconstruct the current version or any
 earlier version.  The repository also contains other information, such
-as @dfn{log entries} that describe the changes made to each file.
+as @dfn{commit messages} that describe the changes made to each file.

 @cindex work file
 @cindex checking out files
@@ -210,7 +210,7 @@
 called the @dfn{work file}.  You can change each work file as you
 would an ordinary file.  After you are done with a set of changes, you
 may @dfn{commit} (or @dfn{check in}) the changes; this records the
-changes in the repository, along with a descriptive log entry.
+changes in the repository, along with a descriptive commit message.

 @cindex working tree
   A directory tree of work files is called a @dfn{working tree}.
@@ -326,9 +326,9 @@

   Projects that use a version control system can have two types of log
 for changes.  One is the log maintained by the version control system:
-each time you commit a change, you fill out a @dfn{log entry} for the
-change (@pxref{Log Buffer}).  This is called the @dfn{version control
-log}.
+each time you commit a change, you fill out a @dfn{commit message} for
+the change (@pxref{Log Buffer}).  This is called the @dfn{version
+control log}.

   The other kind of log is the file @file{ChangeLog} (@pxref{Change
 Log}).  It provides a chronological record of all changes to a large
@@ -480,8 +480,8 @@
 @item
 If every work file in the VC fileset has been modified, commit the
 changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
-desired log entry for the new revision, followed by @kbd{C-c C-c} to
-commit.  @xref{Log Buffer}.
+desired commit message for the new revision, followed by @kbd{C-c C-c}
+to commit.  @xref{Log Buffer}.

 If committing to a shared repository, the commit may fail if the
 repository that has been changed since your last update.  In that
@@ -533,7 +533,7 @@
 @item
 If each file is locked by you and contains changes, commit the
 changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
-desired log entry for the new revision, followed by @kbd{C-c C-c} to
+desired commit message for the new revision, followed by @kbd{C-c C-c} to
 commit (@pxref{Log Buffer}).

 @item
@@ -590,10 +590,11 @@
 @cindex C-c C-c @r{(Log Edit mode)}
 @findex log-edit-done
   When you tell VC to commit a change, it pops up a buffer named
-@file{*vc-log*}.  In this buffer, you should write a @dfn{log entry}
-describing the changes you have made (@pxref{Why Version Control?}).
-After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
-the buffer and commit the change, together with your log entry.
+@file{*vc-log*}.  In this buffer, you should write a @dfn{commit message}
+(a. k. a. log entry) describing the changes you have made
+(@pxref{Why Version Control?}).  After you are done, type @kbd{C-c C-c}
+(@code{log-edit-done}) to exit the buffer and commit the change,
+together with your commit message.

 @cindex Log Edit mode
 @cindex mode, Log Edit
@@ -607,9 +608,9 @@
 lines}, specifying additional information to be supplied to the
 version control system.  Each header line must occupy a single line at
 the top of the buffer; the first line that is not a header line is
-treated as the start of the log entry.  For example, the following
-header line states that the present change was not written by you, but
-by another developer:
+treated as the start of the commit message.  For example, the
+following header line states that the present change was not written
+by you, but by another developer:

 @smallexample
 Author: J. R. Hacker <jrh@@example.com
>
@@ -622,7 +623,7 @@
 systems recognize all headers: Bazaar recognizes all three headers,
 while Git, Mercurial, and Monotone recognize only @samp{Author} and
 @samp{Date}.  If you specify a header for a system that does not
-support it, the header is treated as part of the log entry.
+support it, the header is treated as part of the commit message.

 @kindex C-c C-f @r{(Log Edit mode)}
 @findex log-edit-show-files
@@ -661,12 +662,12 @@
 @kindex M-p @r{(Log Edit mode)}
 @kindex M-s @r{(Log Edit mode)}
 @kindex M-r @r{(Log Edit mode)}
-  You can also browse the history of previous log entries to duplicate
-a commit comment.  This can be useful when you want to make several
-commits with similar comments.  The commands @kbd{M-n}, @kbd{M-p},
-@kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
-history commands (@pxref{Minibuffer History}), except that they are
-used outside the minibuffer.
+  You can also browse the history of previous commit messages to
+duplicate a commit message.  This can be useful when you want to make
+several commits with similar messages.  The commands @kbd{M-n},
+@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
+minibuffer history commands (@pxref{Minibuffer History}), except that
+they are used outside the minibuffer.

 @node Registering
 @subsection Registering a File for Version Control
@@ -833,7 +834,7 @@
   From the annotate buffer, these and other color scaling options are
 available from the @samp{VC-Annotate} menu.  In this buffer, you can
 also use the following keys to browse the annotations of past revisions,
-view diffs, or view log entries:
+view diffs, or view commit messages:

 @table @kbd
 @item p
@@ -908,11 +909,11 @@
   @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
 @file{*vc-change-log*}, showing the history of changes made to the
 current file, including who made the changes, the dates, and the log
-entry for each change (these are the same log entries you would enter
-via the @file{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
-centered at the revision of the file currently being visited.  With a
-prefix argument, the command prompts for the revision to center on,
-and the maximum number of revisions to display.
+entry for each change (these are the same as the commit messages you
+would enter via the @file{*vc-log*} buffer; @pxref{Log Buffer}).
+Point is centered at the revision of the file currently being visited.
+With a prefix argument, the command prompts for the revision to center
+on, and the maximum number of revisions to display.

   If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
 Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
@@ -927,8 +928,8 @@
 maximum number of revisions to display.

   The @kbd{C-x v L} history is shown in a compact form, usually
-showing only the first line of each log entry.  However, you can type
-@key{RET} (@code{log-view-toggle-entry-display}) in the
+showing only the first line of each commit message.  However, you can
+type @key{RET} (@code{log-view-toggle-entry-display}) in the
 @file{*vc-change-log*} buffer to reveal the entire log entry for the
 revision at point.  A second @key{RET} hides it again.

@@ -972,8 +973,8 @@
 Annotate the revision on the current line (@pxref{Old Revisions}).

 @item e
-Modify the change comment displayed at point.  Note that not all VC
-systems support modifying change comments.
+Modify the commit message displayed at point.  Note that not all VC
+systems support modifying commit messages.

 @item f
 Visit the revision indicated at the current line.
@@ -994,7 +995,7 @@
 @end table

 @vindex vc-log-show-limit
-Because fetching many log entries can be slow, the
+Because fetching many commit messages can be slow, the
 @file{*vc-change-log*} buffer displays no more than 2000 revisions by
 default.  The variable @code{vc-log-show-limit} specifies this limit;
 if you set the value to zero, that removes the limit.  You can also

=== modified file 'doc/emacs/vc1-xtra.texi'
--- doc/emacs/vc1-xtra.texi    2013-06-09 11:15:54 +0000
+++ doc/emacs/vc1-xtra.texi    2013-06-14 22:22:01 +0000
@@ -77,11 +77,11 @@
 @end iftex

 @noindent
-If the version control log entry specifies a function name (in
+If the version control commit message specifies a function name (in
 parenthesis at the beginning of a line), that is reflected in the
-@file{ChangeLog} entry.  For example, if a log entry for @file{vc.el}
-is @samp{(vc-do-command): Check call-process status.}, the
-@file{ChangeLog} entry is:
+@file{ChangeLog} entry.  For example, if a commit message for
+@file{vc.el} is @samp{(vc-do-command): Check call-process status.},
+the @file{ChangeLog} entry is:

 @iftex
 @medbreak

=== modified file 'etc/NEWS'
--- etc/NEWS    2013-06-11 21:38:35 +0000
+++ etc/NEWS    2013-06-14 23:00:16 +0000
@@ -446,6 +446,12 @@
 *** `isearch-nonincremental-exit-minibuffer'
 *** `isearch-filter-visible'
 *** `generic-make-keywords-list'
+*** `vc-modify-change-comment'
+*** `vc-svn-modify-change-comment'
+*** `vc-sccs-modify-change-comment'
+*** `vc-rcs-modify-change-comment'
+*** `vc-cvs-modify-change-comment'
+*** `log-view-modify-change-comment'

 ** `with-wrapper-hook' is obsoleted by `add-function'.
 The few hooks that used with-wrapper-hook are replaced as follows:

=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog    2013-06-12 12:12:47 +0000
+++ lisp/ChangeLog    2013-06-14 22:56:31 +0000
@@ -1,3 +1,19 @@
+2013-06-14  Xue Fuqiao  <xfq.free@gmail.com>
+
+    * vc/log-edit.el (log-edit-comment-to-change-log)
+    (log-edit-mode-map, log-edit-insert-changelog, log-edit-menu)
+    (log-edit-require-final-newline, log-edit, log-edit-mode)
+    (log-edit-done, log-edit-add-to-changelog)
+    (log-edit-insert-changelog):
+    * vc/vc.el (vc-modify-change-comment, vc-checkin):
+    * vc/vc-svn.el (vc-svn-modify-change-comment):
+    * vc/vc-sccs.el (vc-sccs-modify-change-comment):
+    * vc/vc-rcs.el (vc-rcs-modify-change-comment):
+    * vc/vc-cvs.el (vc-cvs-modify-change-comment):
+    * vc/log-view.el (log-view-modify-change-comment)
+    (log-view-mode-menu): Uniformize the phrasing for "commit
+    message".
+
 2013-06-12  Xue Fuqiao  <xfq.free@gmail.com>

     * ibuf-ext.el (ibuffer-mark-help-buffers): Doc fix.

=== modified file 'lisp/vc/log-edit.el'
--- lisp/vc/log-edit.el    2013-01-12 03:15:14 +0000
+++ lisp/vc/log-edit.el    2013-06-14 22:56:31 +0000
@@ -60,7 +60,7 @@
     ("\M-r"    . log-edit-comment-search-backward)
     ("\M-s"    . log-edit-comment-search-forward)
     ("\C-c?"    . log-edit-mode-help))
-  "Keymap for the `log-edit-mode' (to edit version control log messages)."
+  "Keymap for the `log-edit-mode' (to edit commit messages)."
   :group 'log-edit)

 ;; Compatibility with old names.  Should we bother ?
@@ -74,9 +74,9 @@
      :help "Exit log-edit and proceed with the actual action."]
     "--"
     ["Insert ChangeLog" log-edit-insert-changelog
-     :help "Insert a log message by looking at the ChangeLog"]
+     :help "Insert a commit message by looking at the ChangeLog"]
     ["Add to ChangeLog" log-edit-add-to-changelog
-     :help "Insert this log message into the appropriate ChangeLog file"]
+     :help "Insert this commit message into the appropriate ChangeLog file"]
     "--"
     ["Show diff" log-edit-show-diff
      :help "Show the diff for the files to be committed."]
@@ -105,7 +105,7 @@
   :type 'boolean)

 (defcustom log-edit-require-final-newline t
-  "Enforce a newline at the end of commit log messages.
+  "Enforce a newline at the end of commit messages.
 Enforce it silently if t, query if non-nil and don't do anything if nil."
   :group 'log-edit
   :type '(choice (const ask) (const t) (const nil)))
@@ -251,7 +251,7 @@
   (log-edit-comment-search-backward str -1))

 (defun log-edit-comment-to-change-log (&optional whoami file-name)
-  "Enter last VC comment into the change log for the current file.
+  "Enter last commit message into the change log for the current file.
 WHOAMI (interactive prefix) non-nil means prompt for user name
 and site.  FILE-NAME is the name of the change log; if nil, use
 `change-log-default-name'.
@@ -268,7 +268,7 @@
     end)
     ;; Call add-log to do half the work.
     (add-change-log-entry whoami file-name t t)
-    ;; Insert the VC comment, leaving point before it.
+    ;; Insert the commit message, leaving point before it.
     (setq end (save-excursion (insert comment) (point-marker)))
     (if (looking-at "\\s *\\s(")
     ;; It starts with an open-paren, as in "(foo): Frobbed."
@@ -401,7 +401,7 @@

 ;;;###autoload
 (defun log-edit (callback &optional setup params buffer mode &rest _ignore)
-  "Setup a buffer to enter a log message.
+  "Setup a buffer to enter a commit message.
 The buffer is put in mode MODE or `log-edit-mode' if MODE is nil.
 \\<log-edit-mode-map>
 If SETUP is non-nil, erase the buffer and run `log-edit-hook'.
@@ -421,7 +421,7 @@
  `vc-log-fileset' -- the VC fileset to be committed (if any).

 If BUFFER is non-nil `log-edit' will jump to that buffer, use it
-to edit the log message and go back to the current buffer when
+to edit the commit message and go back to the current buffer when
 done.  Otherwise, it uses the current buffer."
   (let ((parent (current-buffer)))
     (if buffer (pop-to-buffer buffer))
@@ -450,7 +450,7 @@
           "Press \\[log-edit-done] when you are done editing."))))

 (define-derived-mode log-edit-mode text-mode "Log-Edit"
-  "Major mode for editing version-control log messages.
+  "Major mode for editing version-control commit messages.
 When done editing the log entry, just type \\[log-edit-done] which
 will trigger the actual commit of the file(s).
 Several other handy support commands are provided of course and
@@ -470,7 +470,7 @@
     (bury-buffer buf)))

 (defun log-edit-done ()
-  "Finish editing the log message and commit the files.
+  "Finish editing the commit message and commit the files.
 If you want to abort the commit, simply delete the buffer."
   (interactive)
   ;; Clean up empty headers.
@@ -615,7 +615,7 @@
           (mapconcat 'identity (log-edit-files) "  \n")))

 (defun log-edit-add-to-changelog ()
-  "Insert this log message into the appropriate ChangeLog file."
+  "Insert this commit message into the appropriate ChangeLog file."
   (interactive)
   ;; Yuck!
   (unless (string= (buffer-string) (ring-ref log-edit-comment-ring 0))
@@ -644,7 +644,7 @@
     (insert field ": " value "\n" (if (looking-at "\n") "" "\n"))))

 (defun log-edit-insert-changelog (&optional use-first)
-  "Insert a log message by looking at the ChangeLog.
+  "Insert a commit message by looking at the ChangeLog.
 The idea is to write your ChangeLog entries first, and then use this
 command to commit your changes.


=== modified file 'lisp/vc/log-view.el'
--- lisp/vc/log-view.el    2013-06-11 06:36:06 +0000
+++ lisp/vc/log-view.el    2013-06-14 23:31:47 +0000
@@ -171,8 +171,8 @@
      :help "Visit the version at point"]
     ["Annotate Version"  log-view-annotate-version
      :help "Annotate the version at point"]
-    ["Modify Log Comment" log-view-modify-change-comment
-     :help "Edit the change comment displayed at point"]
+    ["Modify Commit Message" log-view-modify-commit-message
+     :help "Edit the commit message displayed at point"]
     ["Toggle Details at Point" log-view-toggle-entry-display
      :active log-view-expanded-log-entry-function]
     "-----"
@@ -523,13 +523,15 @@
 (declare-function vc-modify-change-comment "vc" (files rev oldcomment))

 (defun log-view-modify-change-comment ()
-  "Edit the change comment displayed at point."
+  "Edit the commit message displayed at point."
   (interactive)
   (vc-modify-change-comment (list (if log-view-per-file-logs
                       (log-view-current-file)
                     (car log-view-vc-fileset)))
                 (log-view-current-tag)
                 (log-view-extract-comment)))
+(define-obsolete-function-alias 'log-view-modify-change-comment
+  'log-view-modify-commit-message)

 (defun log-view-annotate-version (pos)
   "Annotate the version at POS.

=== modified file 'lisp/vc/vc-cvs.el'
--- lisp/vc/vc-cvs.el    2013-06-09 11:15:54 +0000
+++ lisp/vc/vc-cvs.el    2013-06-14 22:48:10 +0000
@@ -496,9 +496,11 @@
       (message "Merging changes into %s...done" file))))

 (defun vc-cvs-modify-change-comment (files rev comment)
-  "Modify the change comments for FILES on a specified REV.
+  "Modify the commit messages for FILES on a specified REV.
 Will fail unless you have administrative privileges on the repo."
   (vc-cvs-command nil 0 files "admin" (concat "-m" rev ":" comment)))
+(define-obsolete-function-alias 'vc-cvs-modify-change-comment
+  'vc-cvs-modify-commit-message)

 ;;;
 ;;; History functions

=== modified file 'lisp/vc/vc-rcs.el'
--- lisp/vc/vc-rcs.el    2013-05-28 07:01:59 +0000
+++ lisp/vc/vc-rcs.el    2013-06-14 22:48:10 +0000
@@ -549,11 +549,14 @@
     (vc-do-command "*vc*" 0 "co" (vc-name file) "-f" (concat "-l" rev))))

 (defun vc-rcs-modify-change-comment (files rev comment)
-  "Modify the change comments change on FILES on a specified REV.  If FILE is a
-directory the operation is applied to all registered files beneath it."
+  "Modify the commit messages change on FILES on a specified REV.
+If FILE is a directory the operation is applied to all registered
+files beneath it."
   (dolist (file (vc-expand-dirs files))
     (vc-do-command "*vc*" 0 "rcs" (vc-name file)
            (concat "-m" rev ":" comment))))
+(define-obsolete-function-alias 'vc-rcs-modify-change-comment
+  'vc-rcs-modify-commit-message)


 ;;;

=== modified file 'lisp/vc/vc-sccs.el'
--- lisp/vc/vc-sccs.el    2013-05-28 07:47:11 +0000
+++ lisp/vc/vc-sccs.el    2013-06-14 22:48:10 +0000
@@ -343,10 +343,12 @@
             (vc-name file) "-g" (if rev (concat "-r" rev)))))

 (defun vc-sccs-modify-change-comment (files rev comment)
-  "Modify (actually, append to) the change comments for FILES on a
specified REV."
+  "Modify (actually, append to) the commit messages for FILES on a
specified REV."
   (dolist (file (vc-expand-dirs files))
     (vc-sccs-do-command nil 0 "cdc" (vc-name file)
                         (concat "-y" comment) (concat "-r" rev))))
+(define-obsolete-function-alias 'vc-sccs-modify-change-comment
+  'vc-sccs-modify-commit-message)


 ;;;

=== modified file 'lisp/vc/vc-svn.el'
--- lisp/vc/vc-svn.el    2013-05-28 07:01:59 +0000
+++ lisp/vc/vc-svn.el    2013-06-14 22:48:10 +0000
@@ -449,7 +449,7 @@
       (message "Merging changes into %s...done" file))))

 (defun vc-svn-modify-change-comment (files rev comment)
-  "Modify the change comments for a specified REV.
+  "Modify the commit messages for a specified REV.
 You must have ssh access to the repository host, and the directory Emacs
 uses locally for temp files must also be writable by you on that host.
 This is only supported if the repository access method is either file://
@@ -487,6 +487,8 @@
            (format "svnadmin setlog --bypass-hooks %s -r %s %s; rm %s"
                directory rev tempfile tempfile))
     (error "Log edit failed")))))
+(define-obsolete-function-alias 'vc-svn-modify-change-comment
+  'vc-svn-modify-commit-message)

 ;;;
 ;;; History functions

=== modified file 'lisp/vc/vc.el'
--- lisp/vc/vc.el    2013-06-11 22:14:30 +0000
+++ lisp/vc/vc.el    2013-06-14 22:48:10 +0000
@@ -338,10 +338,10 @@
 ;;   used for files under this backend, and if files can indeed be
 ;;   locked by other users.
 ;;
-;; - modify-change-comment (files rev comment)
+;; - modify-commit-message (files rev comment)
 ;;
-;;   Modify the change comments associated with the files at the
-;;   given revision.  This is optional, many backends do not support it.
+;;   Modify the commit messages associated with the files at the given
+;;   revision.  This is optional, many backends do not support it.
 ;;
 ;; - mark-resolved (files)
 ;;
@@ -1420,7 +1420,7 @@
     (run-hooks 'vc-before-checkin-hook))
   (vc-start-logentry
    files comment initial-contents
-   "Enter a change comment."
+   "Enter a commit message."
    "*vc-log*"
    (lambda ()
      (vc-call-backend backend 'log-edit-mode))
@@ -1896,12 +1896,14 @@
   (let ((backend (vc-responsible-backend (car files))))
     (vc-start-logentry
      files oldcomment t
-     "Enter a replacement change comment."
+     "Enter a replacement commit message."
      "*vc-log*"
      (lambda () (vc-call-backend backend 'log-edit-mode))
      (lambda (files comment)
        (vc-call-backend backend
                         'modify-change-comment files rev comment)))))
+(define-obsolete-function-alias 'vc-modify-change-comment
+  'vc-modify-commit-message)

 ;;;###autoload
 (defun vc-merge ()

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

bug#14750: [PATCH] Cleanup for "commit message"

[Glenn Morris]

Xue Fuqiao wrote:

> I found that "commit message" is not used consistently.  Maybe we should
> clean this up.

I don't think changing "log entry" for "commit message" everywhere is
desirable. Both terms are widely used, and log appears in the name of
buffers and commands. I agree with the "change-comment" part though.

> +(define-obsolete-function-alias 'log-view-modify-change-comment
> +  'log-view-modify-commit-message)

Should always have a version.

bug#14750: [PATCH] Cleanup for "commit message"

[Stefan Monnier]

>> I found that "commit message" is not used consistently.  Maybe we should
>> clean this up.
> I don't think changing "log entry" for "commit message" everywhere is
> desirable.

It might be a good idea to use the two terms at one place
(e.g. somewhere in the manual).  But after that I think it makes sense
to pick one term and stick to it.


        Stefan

bug#14750: [PATCH] Cleanup for "commit message"

[Glenn Morris]

Stefan Monnier wrote:

> But after that I think it makes sense to pick one term and stick to it.

AFAICS, we do. A quick grep of doc/ suggests at present "commit message"
is only used in a tiny number of places in pcl-cvs.texi and gnus.texi.