From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Is it time to drop ChangeLogs? Date: Fri, 08 Jul 2016 18:25:11 +0300 Message-ID: <83bn28i23s.fsf@gnu.org> References: <83vb50wxhv.fsf@gnu.org> <87y49vz4cg.fsf@acer.localhost.com> <87twg2g86g.fsf@lifelogs.com> <83eg76n5h5.fsf@gnu.org> <87y45eeoor.fsf@lifelogs.com> <8337nmn2pd.fsf@gnu.org> <87shvmem2c.fsf@lifelogs.com> <87oa6adz3w.fsf@lifelogs.com> <577E056B.1060705@cs.ucla.edu> <871t35egck.fsf@lifelogs.com> <577E6697.8090603@cs.ucla.edu> <87furle9tc.fsf@wanadoo.es> <8737nkdy8a.fsf@wanadoo.es> <83h9c0i4wa.fsf@gnu.org> <87lh1ccgo6.fsf@wanadoo.es> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1467991656 13542 80.91.229.3 (8 Jul 2016 15:27:36 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 8 Jul 2016 15:27:36 +0000 (UTC) Cc: emacs-devel@gnu.org To: =?iso-8859-1?Q?=D3scar?= Fuentes Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jul 08 17:27:28 2016 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 1bLXgb-0003rV-4p for ged-emacs-devel@m.gmane.org; Fri, 08 Jul 2016 17:27:25 +0200 Original-Received: from localhost ([::1]:46263 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bLXga-0007XK-7i for ged-emacs-devel@m.gmane.org; Fri, 08 Jul 2016 11:27:24 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39508) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bLXel-0004hz-VV for emacs-devel@gnu.org; Fri, 08 Jul 2016 11:25:33 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bLXeg-0007X3-7a for emacs-devel@gnu.org; Fri, 08 Jul 2016 11:25:31 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:48419) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bLXeg-0007Wm-4W; Fri, 08 Jul 2016 11:25:26 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3407 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bLXed-00056P-Kw; Fri, 08 Jul 2016 11:25:24 -0400 In-reply-to: <87lh1ccgo6.fsf@wanadoo.es> (message from =?iso-8859-1?Q?=D3s?= =?iso-8859-1?Q?car?= Fuentes on Fri, 08 Jul 2016 17:07:05 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:205448 Archived-At: > From: Óscar Fuentes > Date: Fri, 08 Jul 2016 17:07:05 +0200 > > Eli Zaretskii writes: > > >> That information is already available from the VCS, on steroids. You can > >> query the history of a function, ask which changes introduced or deleted > >> a call to certain function... > > > > Yes, but doing so on a large file that saw many changes is relatively > > slow. Scanning a ChangeLog is much faster, so I always use it as the > > first approximation, and only go to the likes of "git log -L" and > > "git annotate" if I have to. > > You rarely are interested on the whole file. vc-region-history makes > wonders when you care about part of the file (a function, for instance.) That's "git log -L" that I mentioned. It's startup time is not negligible. > Remove just input mark > > * lisp/ibuffer.el (ibuffer-unmark-all): When MARK is not ?\r remove > just MARK. > > no hint about why it was necessary. Did you look at the comments? > About 3 commits below: > > Disable App Nap (bug#22993) > > * nextstep/templates/Info.plist.in: Insert AppNap disable code. > > No hint about why it was necessary, except for the bug# Which is more than enough. > Besides, having to jump to the bug is a nuisance > (some people mentioned that having the ChangeLogs readily available on > the tarballs is an advantage.) It is not necessary to duplicate the > whole discussion, but briefly mentioning what the problem was and why it > was decided to solve it this way would be helpful. This request is unreasonable. If nothing else, it will make the bar for contributing higher, not lower. The information is recorded in the bug discussion, and there's no need to reproduce it in the log message. > Yet a two or three commits below: > > Fix an error in Tramp for rsync > > * lisp/net/tramp-sh.el (tramp-do-copy-or-rename-file-out-of-band): > Make it work for "rsync". > (tramp-make-copy-program-file-name): Apply `directory-file-name'. > > There is no even bug # here. > > And so on. I see no problems in these log messages. > > This conflates several distinct places where this information is held, > > making it sound that all of it should be in the commit log message. > > That is false, or at least I couldn't disagree more. First and > > foremost, the code should speak for itself, so the most detailed > > explanations should be in comments there. We didn't just replace the > > code by the VCS! > > I never said otherwise. I talked about the "right place" for putting > information on the next paragraph. Which we already do. Improvements are always possible, but by and large our commit log messages are good. > > Second, many times the information is in a prolonged discussion, in > > particular on the bug tracker. By including a reference to the bug > > report, we implicitly include all of it in the log message. > > It is not helpful to point the reader to a long discussion if the > rationale for the change can be summarized (mentioning the bug# is a > good thing, of course.) There's no other practical way. It's unreasonable to ask people to summarize such discussions in a log message. > > As for "the diff is readily available, there is no need to name each > > function touched by the change" part, it is inaccurate: the VCS diff > > tool doesn't always show the name of the function or macro that is > > being changed. Moreover, if several functions/macros are changed in a > > single hunk, at most one of them will be named in the hunk header, the > > rest need to be deduced by painfully reading the diffs. I don't think > > we can say in good faith that this information is as readily available > > as in ChangeLog-style log messages. > > Possibly not as readily available but, to be fair, how many times you > are interested on the functions affected on a trivial way by a change? Always. For me, digging into an issue usually begins with a function I know is misbehaving. The very next question is: when was it last changed, how, and why. > Usually you are interested on either how a given function evolved or on > how the introduction of a fix/feature affected the code base. No, that's rarely the case. It only happens when I find a very old bug, and am curious who and when introduced it. > > I find comments to be a better place for these situations as well (and > > made many comments of this kind over the years myself). The most > > important reason is discoverability: when one reads code, they usually > > won't look at the Git history of the code they go through, but > > comments they will see. Scattered changes are not a problem, you can > > always say "see such-and-such function". > > I see this on a different way: commit messages add to, and complement, > code comments. They shouldn't.