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 17:24:53 +0300 Message-ID: <83h9c0i4wa.fsf@gnu.org> References: <4hd1rw1ubr.fsf@fencepost.gnu.org> <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> 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 1467987930 15767 80.91.229.3 (8 Jul 2016 14:25:30 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 8 Jul 2016 14:25:30 +0000 (UTC) Cc: rms@gnu.org, 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 16:25:30 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 1bLWid-0004LT-Ir for ged-emacs-devel@m.gmane.org; Fri, 08 Jul 2016 16:25:27 +0200 Original-Received: from localhost ([::1]:45930 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bLWic-0003bG-SI for ged-emacs-devel@m.gmane.org; Fri, 08 Jul 2016 10:25:26 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52917) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bLWiT-0003Yo-Jz for emacs-devel@gnu.org; Fri, 08 Jul 2016 10:25:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bLWiO-0002p2-Po for emacs-devel@gnu.org; Fri, 08 Jul 2016 10:25:17 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:47639) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bLWiO-0002ok-MX; Fri, 08 Jul 2016 10:25:12 -0400 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3358 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1bLWiE-0006of-T7; Fri, 08 Jul 2016 10:25:03 -0400 In-reply-to: <8737nkdy8a.fsf@wanadoo.es> (message from =?iso-8859-1?Q?=D3s?= =?iso-8859-1?Q?car?= Fuentes on Fri, 08 Jul 2016 16:02:29 +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:205439 Archived-At: > From: Óscar Fuentes > Date: Fri, 08 Jul 2016 16:02:29 +0200 > Cc: emacs-devel@gnu.org > > Richard Stallman writes: > > > > GNU ChangeLogs, as used in practice, are so lame and thin on content > > > that they certainly can't be taken seriously as a method of documenting > > > changes. > > > > They are good for their purpose, which is to summarize which functions > > or objects were changed, when, and by whom. That's useful when > > you want to see which changes to look at to figure out when a bug > > got introduced. > > 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. > But the real damage ChangeLogs cause is their formulaic, almost mechanic > aspect: people write a lot of minutiae instead of writing a commit > message intended to help the reader, the same way good code comments are > written. It is true that some hackers write good commit messages *and* > ChangeLogs, but I'm under the impression that most people just write the > changelog and consider that their job is done (after all, current policy > for commit messages is to write a summary line and the You are invited to look at our recent commit log messages, which are in the ChangeLog format, and point out the ones that fit the above description. I don't think you will find a lot of them, but maybe I'm mistaken. > In a nutshell, a proper commit message shall contain, either explicitly > or implicitly, the what, why, where and how of the change. It must be > informative and provide the info that the reader is interested on, > without entering on unnecessary detail (the diff is readily available, > there is no need to name each function touched by the change). The > author must write it with the same mindset he chooses function and > variable names, decides when it is a good idea to put a code comment, > etc. 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! 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. 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. > Some times, however, the code is not the best place to put some > explanation (think of an scattered change or why some alternative that, > at first, seems more adequate was discarded) and the commit message > offers an alternative. The commit message is a good place to direct the > reader to the key areas for understanding the change, inform the reader > about current status and future steps and any other info that the author > thinks is relevant for current and/or future hackers with an interest on > the affected area. 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". > > > GNU ChangeLogs always looked to me as cargo cult and an excuse for not > > > writing proper commit messages. > > > > There was no such thing as a commit message in 1985. > > Exactly. I'm pretty sure that if you had a good VCS at that time > ChangeLogs would never came into being. If history went another way, perhaps we wouldn't have Emacs as well. More to the point, fact is that no better methodology was invented. So history is not the only reason why we are still using this format.