1
0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-23 10:34:07 +00:00

Update with Miles's advice on how to commit.

This commit is contained in:
Glenn Morris 2010-01-16 12:24:08 -08:00
parent 617364feb7
commit 4572d05251

View File

@ -1,15 +1,53 @@
HOW TO COMMIT CHANGES TO EMACS
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
(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 entiries (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".
Followup discussion:
http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.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
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