* admin/mac/uvs.el: New file from Mac port. src/macuvs.h is generated by it.
[emacs.git] / admin / notes / commits
blobf33c6905d4cfc182266635a4fc297ae62c60d09c
1 HOW TO COMMIT CHANGES TO EMACS
3 Most of these points are from:
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
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).
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.
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).
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:
29         SHORTISH ONE-LINE SUMMARY
31         MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
32         CONSISTING OF) CHANGELOG ENTRIES
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.]
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.
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".
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.
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
63 PREVIOUS GUIDELINES FOR CVS
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
68 From: Eli Zaretskii
69 Subject: Re: Log messages in CVS
70 Date: Sat, 29 Dec 2007 16:06:29 +0200