Re: More metaproblem

[Stephen Leake]

Eli Zaretskii <address@hidden> writes:

>> "Eric S. Raymond" <address@hidden> writes:
>> >For Emacs to attract new developers, its code and the culture need to
>> >be discoverable.  As part of this, practice rules need to be *clear*,
>> >*documented*, and *minimal*.  Right now they fail all three tests.
>>
> See admin/notes/repo and admin/notes/commits.  What else is missing?

That does not describe the changelog entry/commit message format. There
is admin/notes/changelog, which contains a reference to the Gnu coding
standards and some hints.

admin/notes/commits explictly says the commit message does _not_ need to
contain all the info the Changelog entry does; that is apparently
incorrect.

It also assumes CVS, while at the same time allowing for other systems;
confusing.

It would help if the emails that say "please follow the standard style"
would mention these documents, so people get used to refering to them.

Proposed patch for repo in another email; patches for commits,
changelogs:

diff --git a/admin/notes/changelogs b/admin/notes/changelogs
index e815806..503b73a 100644
--- a/admin/notes/changelogs
+++ b/admin/notes/changelogs
@@ -30,3 +30,13 @@ Preferred form for several entries with the same content:
    * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.

 (Rather than anything involving "ditto" and suchlike.)
+
+In ChangeLog files, it is best to use ways of identifying revisions
+that are not dependent on a particular version control system.  (At
+time of writing Emacs has just moved to its fourth VCS and another
+move in the future is not impossible.)  An excellent way to identify
+commits is by quoting their summary line.  Another is with an action
+stamp - an RFC3339 date followed by ! followed by the committer's
+email - for example, "2014-01-16T05:43:address@hidden". Often,
+"my previous commit" will suffice.
+
diff --git a/admin/notes/commits b/admin/notes/commits
index f33c690..5371b2b 100644
--- a/admin/notes/commits
+++ b/admin/notes/commits
@@ -1,70 +1,27 @@
 HOW TO COMMIT CHANGES TO EMACS

-Most of these points are from:
-
-http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html
-From:   Miles Bader
-Subject: commit style redux
-Date:   Tue, 31 Mar 2009 12:21:20 +0900
-
 (0) Each commit should correspond to a single change (whether spread
     over multiple files or not).  Do not mix different changes in the
     same commit (eg adding a feature in one file, fixing a bug in
     another should be two commits, not one).

-(1) Commit all changed files at once with a single log message (which
-    in CVS will result in an identical log message for all committed
-    files), not one-by-one.  This is pretty easy using vc-dir now.
-
-(2) Make the log message describe the entire changeset, perhaps
-    including relevant changelog entries (I often don't bother with
-    the latter if it's a trivial sort of change).
-
-    Many modern source-control systems vaguely distinguish the first
-    line of the log message to use as a short summary for abbreviated
-    history listing (in arch this was explicitly called the summary,
-    but many other systems have a similar concept).  So it's nice if
-    you can format the log entry like:
-
-        SHORTISH ONE-LINE SUMMARY
-
-        MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
-        CONSISTING OF) CHANGELOG ENTRIES
+(1) Commit all changed files at once with a single log message (the
+    default behavior in git).

-    [Even with CVS this style is useful, because web CVS browsing
-    interfaces often include the first N words of the log message of
-    the most recent commit as a short "most recent change"
-    description.]
-
-(3) Don't phrase log messages assuming the filename is known, because
-    in non-file-oriented systems (everything modern other than CVS),
-    the log listing tends to be treated as global information, and the
-    connection with specific files is less explicit.
-
-    For instance, currently I often see log messages like "Regenerate";
-    for modern source-control systems with a global log, it's better to
-    have something like "Regenerate configure".
-
-(4) (Added in 2014) In commit comments, and ChangeLog files, it is best
-    to use ways of identifying revisions that are not dependent on a
-    particular version control system.  (At time of writing Emacs is
-    about to move to its fourth VCS and another move in the future is
-    not impossible.)  An excellent way to identify commits is by
-    quoting their summary line.  Another is with an action stamp - an
-    RFC3339 date followed by ! followed by the committer's email - for
-    example, "2014-01-16T05:43:address@hidden". Often, "my
-    previous commit" will suffice.
-
-Followup discussion:
-http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
-http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html
+(2) Make the log message describe the entire changeset. The log
+    message should be the same as the Changelog entry, without the
+    date line. You can write the Changelog first, then use C-c C-a
+    from the *VC-Log* buffer to copy it to the commit log message. See
+    the file 'changelog' for information on the Changelog entry
+    format.

+(3) If committing changes written by someone else, make the ChangeLog
+    entry in their name, not yours. git distinguishes between the
+    author and the committer; use the --author option on the commit
+    command to specify the actual author; the committer defaults to
+    you.

 PREVIOUS GUIDELINES FOR CVS

 For historical interest only, here is the old-style advice for CVS logs:
 http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
-
-From: Eli Zaretskii
-Subject: Re: Log messages in CVS
-Date: Sat, 29 Dec 2007 16:06:29 +0200


--
-- Stephe