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
  49 Followup discussion:
  50 http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
  51 http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html
  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