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: Mon, 07 Mar 2016 18:30:53 +0200 Message-ID: <837fheuu6a.fsf@gnu.org> References: <56BE7E37.3090708@cs.ucla.edu> <4hd1rw1ubr.fsf@fencepost.gnu.org> <83vb50wxhv.fsf@gnu.org> <87y49vz4cg.fsf@acer.localhost.com> <87vb4zb0i4.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1457368280 20761 80.91.229.3 (7 Mar 2016 16:31:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 7 Mar 2016 16:31:20 +0000 (UTC) Cc: emacs-devel@gnu.org To: Mathieu Lirzin Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Mar 07 17:31:20 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 1acy3u-0005UV-G0 for ged-emacs-devel@m.gmane.org; Mon, 07 Mar 2016 17:31:14 +0100 Original-Received: from localhost ([::1]:56866 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1acy3t-0008LK-U1 for ged-emacs-devel@m.gmane.org; Mon, 07 Mar 2016 11:31:13 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56307) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1acy3Y-0008K9-8Q for emacs-devel@gnu.org; Mon, 07 Mar 2016 11:30:56 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1acy3U-00020N-9K for emacs-devel@gnu.org; Mon, 07 Mar 2016 11:30:52 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:47117) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1acy3U-00020J-58 for emacs-devel@gnu.org; Mon, 07 Mar 2016 11:30:48 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:1296 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1acy3S-0008Nc-Vx; Mon, 07 Mar 2016 11:30:47 -0500 In-reply-to: <87vb4zb0i4.fsf@gnu.org> (message from Mathieu Lirzin on Mon, 07 Mar 2016 01:22:11 +0100) 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.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:201054 Archived-At: > From: Mathieu Lirzin > Date: Mon, 07 Mar 2016 01:22:11 +0100 > Cc: 21998@debbugs.gnu.org, Lars Magne Ingebrigtsen > > In my short experience, Change Logs has generally been useful both when > reading and composing them. When writing them it helps me structure > large changes in logical commits that are modelled by the Change Log > format. Finally It helps me being precise in my wordings which is not > trivial for non-native english speakers. > > On a more spiritual side, I think they belong to the zen of contributing > to a GNU project. :) I agree completely. Writing a log entry in ChangeLog format is an excellent opportunity for reflecting on the changeset, for summarizing its intent and final shape, and for making sure nothing was left out. Writing those entries teaches one discipline, the ability to describe your changes in just enough detail, and facilitates communications between members of the development team. And in loose teams such as ours, good communications are everything. As told many times in past discussions, ChangeLog files are also an excellent first tool for forensics, easy to search with many available tools. It is invaluable when you don't have access to the repository, and a good asset even if you do: traversing the history of a complex Git repo without missing commits on branches is not a trivial task, it requires using non-default switches and some rarely used commands and options. Even when you do use Git tools, ChangeLog frequently provides additional important evidence. So removing ChangeLog files will be a bad blow to our ability to easily and conveniently research the past, something that is extremely important in a project with such a rich history, where it's all too easy to reintroduce a bug if you don't look hard enough at the history of some code fragment. People are saying it's an extra barrier to contributing. That is true, but so is understanding the Emacs internals, code conventions, organization of the documentation system, its auxiliary files (like CONTRIBUTE, NEWS, DEBUG, PROBLEMS, etc.), the release process, and a few more things. Having to write ChangeLog entries is an insignificant addition to the body of knowledge a contributor needs to master, there's no way around that. Nor should there be: without knowing this stuff, you cannot be a useful contributor anyway, as your contributions will need too much attention from the veterans, who then will be unable to make more significant contributions due to lack of time. We need here contributors who know enough to work on their own with minimal guidance, who can be trusted to do a good job that doesn't need to be reviewed too deeply, whose design can be trusted to be in line with the Emacsy way of doing things. How can one raise to this position without learning a lot of project-specific stuff? You can't. Writing ChangeLog entries is just one small part of that. It's no accident that people who don't want ChangeLog files more often than not don't want to write detailed commit log messages, either, and many times don't know how to write good documentation. Do we want to dispense with these as well? If we drop the ChangeLog files, there's no way we can explain why we ask for commit log messages in ChangeLog format, so the next logical step is to drop that as well, and we will then lose valuable information. We already are firmly on that path. Other prominent GNU projects that maintain ChangeLog files in the repository include GCC, Binutils, GDB, glibc, and Texinfo. XEmacs also has it. Why should Emacs be the first one to plunge into this adventure? Why not let others try that first, so that we could later learn from their mistakes? We have more important things to do than waste our scarce resources on side issues, and too few people to do them. Let's reinstate the ChangeLog files. Maintaining them is a negligible cost; many other projects do that and don't have any trouble. Unlike what some people say, merge conflicts in ChangeLog files are very rare, once you install git-merge-changelog. We have some important infrastructure based on ChangeLog files that will become extinct without them, something that people tend to forget. We tried to live without these files for a year; that experiment failed miserably. It's time to admit that, and fix the mistake we made.