From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stephen Leake Newsgroups: gmane.emacs.devel Subject: Re: More metaproblem Date: Thu, 04 Dec 2014 03:08:14 -0600 Message-ID: <85egsfpytd.fsf@stephe-leake.org> References: <20141203142859.24393.98673@vcs.savannah.gnu.org> <20141203192721.GE12748@thyrsus.com> <547F6774.50700@cs.ucla.edu> <838uio5vjw.fsf@gnu.org> <20141203211447.GB15111@thyrsus.com> <871toge5zw.fsf@floss.red-bean.com> <83388v6hsq.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1417684117 30673 80.91.229.3 (4 Dec 2014 09:08:37 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 4 Dec 2014 09:08:37 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Dec 04 10:08:31 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1XwSOl-0007j2-JO for ged-emacs-devel@m.gmane.org; Thu, 04 Dec 2014 10:08:31 +0100 Original-Received: from localhost ([::1]:44993 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwSOl-0004bu-5N for ged-emacs-devel@m.gmane.org; Thu, 04 Dec 2014 04:08:31 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40460) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwSOc-0004Z8-LH for emacs-devel@gnu.org; Thu, 04 Dec 2014 04:08:28 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XwSOX-0000s0-5W for emacs-devel@gnu.org; Thu, 04 Dec 2014 04:08:22 -0500 Original-Received: from dnvrco-outbound-snat.email.rr.com ([107.14.73.231]:42391 helo=dnvrco-oedge-vip.email.rr.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwSOW-0000r6-Ts for emacs-devel@gnu.org; Thu, 04 Dec 2014 04:08:17 -0500 Original-Received: from [70.94.38.149] ([70.94.38.149:49705] helo=TAKVER) by dnvrco-oedge02 (envelope-from ) (ecelerity 3.5.0.35861 r(Momo-dev:tip)) with ESMTP id 0F/A3-16151-F7420845; Thu, 04 Dec 2014 09:08:16 +0000 In-Reply-To: <83388v6hsq.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 04 Dec 2014 08:38:29 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.94 (windows-nt) X-RR-Connecting-IP: 107.14.64.130:25 X-Authority-Analysis: v=2.1 cv=bePlUY/B c=1 sm=1 tr=0 a=AppmJ/7ZOOFWL/q6u6u93g==:117 a=AppmJ/7ZOOFWL/q6u6u93g==:17 a=ayC55rCoAAAA:8 a=fNEgcOh0sVsA:10 a=9i_RQKNPAAAA:8 a=mDV3o1hIAAAA:8 a=Nby5tkL7AAAA:8 a=NhiTccdcWpZ8anSjVw0A:9 a=OGmvnhsrd4QA:10 a=MduLXYboLQMA:10 a=VOaXQuoSg2oA:10 a=y9zyDw61hH0A:10 a=qVC7CIU-IH0A:10 X-Cloudmark-Score: 0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 107.14.73.231 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:178807 Archived-At: Eli Zaretskii writes: >> "Eric S. Raymond" 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:35Z!esr@thyrsus.com". 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:35Z!esr@thyrsus.com". 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