admin/notes/commits

   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