From 4572d05251f0b1eeca32a11b6315188623ad8341 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sat, 16 Jan 2010 12:24:08 -0800 Subject: Update with Miles's advice on how to commit. --- admin/notes/commits | 58 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/admin/notes/commits b/admin/notes/commits index ff2dcc93ff..2896328c66 100644 --- a/admin/notes/commits +++ b/admin/notes/commits @@ -1,15 +1,53 @@ -http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html +HOW TO COMMIT CHANGES TO EMACS -From: Eli Zaretskii -Subject: Re: Log messages in CVS -Date: Sat, 29 Dec 2007 16:06:29 +0200 +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 -I once posted a summary that I know about; see: + [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.] - 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 +(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. -Richard commented here, basically approving my summary: + 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". - http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00276.html + +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 -- cgit v1.2.3