Merge from emacs-24; up to 2014-06-02T14:17:07Z!michael.albinus@gmx.de

[bpt/emacs.git] / admin / notes / commits

diff --git a/admin/notes/commits b/admin/notes/commits
dissimilarity index 70%
index ff2dcc9..f33c690 100644 (file)
--- a/admin/notes/commits
+++ b/admin/notes/commits
@@ -1,15 +1,70 @@
-http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
-
-From: Eli Zaretskii
-Subject: Re: Log messages in CVS
-Date: Sat, 29 Dec 2007 16:06:29 +0200
-
-I once posted a summary that I know about; see:
-
-  http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00229.html
-  http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00234.html
-  http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00312.html
-
-Richard commented here, basically approving my summary:
-
-  http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00276.html
+HOW TO COMMIT CHANGES TO EMACS
+
+Most of these points are from:
+
+http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html
+From:   Miles Bader
+Subject: commit style redux
+Date:   Tue, 31 Mar 2009 12:21:20 +0900
+
+(0) Each commit should correspond to a single change (whether spread
+    over multiple files or not).  Do not mix different changes in the
+    same commit (eg adding a feature in one file, fixing a bug in
+    another should be two commits, not one).
+
+(1) Commit all changed files at once with a single log message (which
+    in CVS will result in an identical log message for all committed
+    files), not one-by-one.  This is pretty easy using vc-dir now.
+
+(2) Make the log message describe the entire changeset, perhaps
+    including relevant changelog entries (I often don't bother with
+    the latter if it's a trivial sort of change).
+
+    Many modern source-control systems vaguely distinguish the first
+    line of the log message to use as a short summary for abbreviated
+    history listing (in arch this was explicitly called the summary,
+    but many other systems have a similar concept).  So it's nice if
+    you can format the log entry like:
+
+        SHORTISH ONE-LINE SUMMARY
+
+        MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
+        CONSISTING OF) CHANGELOG ENTRIES
+
+    [Even with CVS this style is useful, because web CVS browsing
+    interfaces often include the first N words of the log message of
+    the most recent commit as a short "most recent change"
+    description.]
+
+(3) Don't phrase log messages assuming the filename is known, because
+    in non-file-oriented systems (everything modern other than CVS),
+    the log listing tends to be treated as global information, and the
+    connection with specific files is less explicit.
+
+    For instance, currently I often see log messages like "Regenerate";
+    for modern source-control systems with a global log, it's better to
+    have something like "Regenerate configure".
+
+(4) (Added in 2014) In commit comments, and ChangeLog files, it is best
+    to use ways of identifying revisions that are not dependent on a
+    particular version control system.  (At time of writing Emacs is
+    about to move to its fourth VCS and another move in the future is
+    not impossible.)  An excellent way to identify commits is by
+    quoting their summary line.  Another is with an action stamp - an
+    RFC3339 date followed by ! followed by the committer's email - for
+    example, "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my
+    previous commit" will suffice.
+
+Followup discussion:
+http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
+http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html
+
+
+PREVIOUS GUIDELINES FOR CVS
+
+For historical interest only, here is the old-style advice for CVS logs:
+http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
+
+From: Eli Zaretskii
+Subject: Re: Log messages in CVS
+Date: Sat, 29 Dec 2007 16:06:29 +0200