From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Stephen J. Turnbull" Newsgroups: gmane.emacs.devel Subject: Re: Org merge Date: Mon, 11 Nov 2013 12:31:50 +0900 Message-ID: <87wqkfipg9.fsf@uwakimon.sk.tsukuba.ac.jp> References: <8738n5cijg.fsf@bzg.ath.cx> <87vc0016yy.fsf@bzg.ath.cx> <87iow0p1n1.fsf@gmail.com> <87bo1s14yr.fsf@bzg.ath.cx> <87li0vvqay.fsf@bzg.ath.cx> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Trace: ger.gmane.org 1384140741 30276 80.91.229.3 (11 Nov 2013 03:32:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 11 Nov 2013 03:32:21 +0000 (UTC) Cc: Stefan Monnier , emacs-devel@gnu.org To: Bastien Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Nov 11 04:32:25 2013 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 1VfiEj-0005vA-1C for ged-emacs-devel@m.gmane.org; Mon, 11 Nov 2013 04:32:25 +0100 Original-Received: from localhost ([::1]:34512 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VfiEi-0006ql-IW for ged-emacs-devel@m.gmane.org; Sun, 10 Nov 2013 22:32:24 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36370) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VfiEY-0006pj-41 for emacs-devel@gnu.org; Sun, 10 Nov 2013 22:32:21 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VfiEQ-0005SH-Jj for emacs-devel@gnu.org; Sun, 10 Nov 2013 22:32:14 -0500 Original-Received: from mgmt2.sk.tsukuba.ac.jp ([130.158.97.224]:49080) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VfiEI-0005RN-NN; Sun, 10 Nov 2013 22:31:58 -0500 Original-Received: from uwakimon.sk.tsukuba.ac.jp (uwakimon.sk.tsukuba.ac.jp [130.158.99.156]) by mgmt2.sk.tsukuba.ac.jp (Postfix) with ESMTP id 80FB89708DB; Mon, 11 Nov 2013 12:31:50 +0900 (JST) Original-Received: by uwakimon.sk.tsukuba.ac.jp (Postfix, from userid 1000) id 731F511EEFA; Mon, 11 Nov 2013 12:31:50 +0900 (JST) In-Reply-To: <87li0vvqay.fsf@bzg.ath.cx> X-Mailer: VM undefined under 21.5 (beta34) "kale" 182d01410b8d XEmacs Lucid (x86_64-unknown-linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 130.158.97.224 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:165138 Archived-At: Bastien writes: > > The usual course of action for new functions is to describe them in > > ChangeLog as: > > > > (foo, bar, baz): New function. > > > > so other than enumerating them, there's nothing to do. > > Yes -- my point was that some functions that are currently listed as > "new functions" in the Changelog I posted are part of the clean room > implementation, others are new functions corresponding to new > features. I will clean up the Changelog to only document the > latter. No, the point of the ChangeLog entry is to make it straightforward to find out what identifiers (functions and variables) are new (for review at the time of integration), and when they were introduced (for context in debugging and study later). You should list all new global identifiers (functions and variables). It's not necessary (although some projects prefer to do so) to document the functionality added in the ChangeLog -- the docstring or comment in the code does that for developers, and NEWS does it in cases where the new identifier is something that users use. N.B. Making such a list is something that can't be done (at least not trivially) with the VCS itself; the developer has to do it mostly by hand. Steve