Mercurial > emacs
annotate admin/notes/commits @ 107283:396dc65ad74c
Merge from mainline.
author | Katsumi Yamaoka <yamaoka@jpl.org> |
---|---|
date | Thu, 18 Feb 2010 21:54:17 +0000 |
parents | 68e28bd7d00a 36d0fedf13ca |
children |
rev | line source |
---|---|
106868
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
1 HOW TO COMMIT CHANGES TO EMACS |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
2 |
107181
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
3 Most of these points are from: |
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
4 |
106868
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
5 http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
6 From: Miles Bader |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
7 Subject: commit style redux |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
8 Date: Tue, 31 Mar 2009 12:21:20 +0900 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
9 |
107181
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
10 (0) Each commit should correspond to a single change (whether spread |
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
11 over multiple files or not). Do not mix different changes in the |
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
12 same commit (eg adding a feature in one file, fixing a bug in |
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
13 another should be two commits, not one). |
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
14 |
106868
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
15 (1) Commit all changed files at once with a single log message (which |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
16 in CVS will result in an identical log message for all committed |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
17 files), not one-by-one. This is pretty easy using vc-dir now. |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
18 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
19 (2) Make the log message describe the entire changeset, perhaps |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
20 including relevant changelog entiries (I often don't bother with |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
21 the latter if it's a trivial sort of change). |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
22 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
23 Many modern source-control systems vaguely distinguish the first |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
24 line of the log message to use as a short summary for abbreviated |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
25 history listing (in arch this was explicitly called the summary, |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
26 but many other systems have a similar concept). So it's nice if |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
27 you can format the log entry like: |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
28 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
29 SHORTISH ONE-LINE SUMMARY |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
30 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
31 MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
32 CONSISTING OF) CHANGELOG ENTRIES |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
33 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
34 [Even with CVS this style is useful, because web CVS browsing |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
35 interfaces often include the first N words of the log message of |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
36 the most recent commit as a short "most recent change" |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
37 description.] |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
38 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
39 (3) Don't phrase log messages assuming the filename is known, because |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
40 in non-file-oriented systems (everything modern other than CVS), |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
41 the log listing tends to be treated as global information, and the |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
42 connection with specific files is less explicit. |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
43 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
44 For instance, currently I often see log messages like "Regenerate"; |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
45 for modern source-control systems with a global log, it's better to |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
46 have something like "Regenerate configure". |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
47 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
48 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
49 Followup discussion: |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
50 http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html |
107181
36d0fedf13ca
* commits: Mention not to mix changes in any given commit.
Glenn Morris <rgm@gnu.org>
parents:
106868
diff
changeset
|
51 http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html |
106868
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
52 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
53 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
54 PREVIOUS GUIDELINES FOR CVS |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
55 |
a3ab0fab30ae
Update with Miles's advice on how to commit.
Glenn Morris <rgm@gnu.org>
parents:
106866
diff
changeset
|
56 For historical interest only, here is the old-style advice for CVS logs: |
92045 | 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 |