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

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
Commit	Line	Data
4572d052	1	HOW TO COMMIT CHANGES TO EMACS
796abee9	2
4572d052 GM	3	http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html
	4	From: Miles Bader
	5	Subject: commit style redux
	6	Date: Tue, 31 Mar 2009 12:21:20 +0900
	7
	8	(1) Commit all changed files at once with a single log message (which
	9	in CVS will result in an identical log message for all committed
	10	files), not one-by-one. This is pretty easy using vc-dir now.
	11
	12	(2) Make the log message describe the entire changeset, perhaps
	13	including relevant changelog entiries (I often don't bother with
	14	the latter if it's a trivial sort of change).
	15
	16	Many modern source-control systems vaguely distinguish the first
	17	line of the log message to use as a short summary for abbreviated
	18	history listing (in arch this was explicitly called the summary,
	19	but many other systems have a similar concept). So it's nice if
	20	you can format the log entry like:
	21
	22	SHORTISH ONE-LINE SUMMARY
	23
	24	MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
	25	CONSISTING OF) CHANGELOG ENTRIES
796abee9	26
4572d052 GM	27	[Even with CVS this style is useful, because web CVS browsing
	28	interfaces often include the first N words of the log message of
	29	the most recent commit as a short "most recent change"
	30	description.]
796abee9	31
4572d052 GM	32	(3) Don't phrase log messages assuming the filename is known, because
	33	in non-file-oriented systems (everything modern other than CVS),
	34	the log listing tends to be treated as global information, and the
	35	connection with specific files is less explicit.
796abee9	36
4572d052 GM	37	For instance, currently I often see log messages like "Regenerate";
	38	for modern source-control systems with a global log, it's better to
	39	have something like "Regenerate configure".
796abee9	40
4572d052 GM	41
	42	Followup discussion:
	43	http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
	44
	45
	46	PREVIOUS GUIDELINES FOR CVS
	47
	48	For historical interest only, here is the old-style advice for CVS logs:
	49	http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
	50
	51	From: Eli Zaretskii
	52	Subject: Re: Log messages in CVS
	53	Date: Sat, 29 Dec 2007 16:06:29 +0200