diff options
| author | Stephen Leake | 2014-12-06 02:11:36 -0600 |
|---|---|---|
| committer | Stephen Leake | 2014-12-06 02:38:34 -0600 |
| commit | 06264b3d247b21be627d1bcd7d928cd3140d249a (patch) | |
| tree | d47798b293468d4a60a185f4c62e2cda64601627 /admin/notes/commits | |
| parent | 7841e9348276c076eb6be26683ee25f0e0db4706 (diff) | |
| download | emacs-06264b3d247b21be627d1bcd7d928cd3140d249a.tar.gz emacs-06264b3d247b21be627d1bcd7d928cd3140d249a.zip | |
Improve CONTRIBUTE and related files.
* CONTRIBUTE: improve; add explicit web references, move some info from
admin/notes/* here.
* INSTALL.REPO: You can't "just run make" after a clean checkout.
* admin/notes/commits: deleted; merged into ./CONTRIBUTE
* admin/notes/repo: move commit, branch info into ./CONTRIBUTE
Diffstat (limited to 'admin/notes/commits')
| -rw-r--r-- | admin/notes/commits | 70 |
1 files changed, 0 insertions, 70 deletions
diff --git a/admin/notes/commits b/admin/notes/commits deleted file mode 100644 index f33c6905d4c..00000000000 --- a/admin/notes/commits +++ /dev/null | |||
| @@ -1,70 +0,0 @@ | |||
| 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 | ||