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