| | 1 | HOW TO COMMIT CHANGES TO EMACS |
| | 2 | |
| | 3 | Most of these points are from: |
| | 4 | |
| | 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 | |
| | 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 | |
| | 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 |
| | 20 | including relevant changelog entries (I often don't bother with |
| | 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 |
| | 33 | |
| | 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.] |
| | 38 | |
| | 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. |
| | 43 | |
| | 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". |
| | 47 | |
| | 48 | (4) (Added in 2014) In commit comments, and ChangeLog files, it is best |
| | 49 | to use ways of identifying revisions that are not dependent on a |
| | 50 | particular version control system. (At time of writing Emacs is |
| | 51 | about to move to its fourth VCS and another move in the future is |
| | 52 | not impossible.) An excellent way to identify commits is by |
| | 53 | quoting their summary line. Another is with an action stamp - an |
| | 54 | RFC3339 date followed by ! followed by the committer's email - for |
| | 55 | example, "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my |
| | 56 | previous commit" will suffice. |
| | 57 | |
| | 58 | Followup discussion: |
| | 59 | http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html |
| | 60 | http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html |
| | 61 | |
| | 62 | |
| | 63 | PREVIOUS GUIDELINES FOR CVS |
| | 64 | |
| | 65 | For historical interest only, here is the old-style advice for CVS logs: |
| | 66 | http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html |
| | 67 | |
| | 68 | From: Eli Zaretskii |
| | 69 | Subject: Re: Log messages in CVS |
| | 70 | Date: Sat, 29 Dec 2007 16:06:29 +0200 |
HCoop / bpt / emacs.git / blame_incremental