From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: David Engster Newsgroups: gmane.emacs.devel Subject: Re: Generating the ChangeLog files from the commit messages Date: Fri, 21 Nov 2014 17:19:30 +0100 Message-ID: <87tx1ssezx.fsf@engster.org> References: <21606.10799.112099.788101@a1i15.kph.uni-mainz.de> <1753218.Ot8JCqssfN@descartes> <546AABCF.8030705@cs.ucla.edu> <9xioico2nm.fsf@fencepost.gnu.org> <87zjbntvfz.fsf@bzg.ath.cx> <87k32rta32.fsf@engster.org> <87a93mu7mo.fsf@engster.org> <83egsw50rr.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1416586880 31631 80.91.229.3 (21 Nov 2014 16:21:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 21 Nov 2014 16:21:20 +0000 (UTC) Cc: bzg@gnu.org, monnier@IRO.UMontreal.CA, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 21 17:21:14 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 1XrqxO-0008MN-5P for ged-emacs-devel@m.gmane.org; Fri, 21 Nov 2014 17:21:14 +0100 Original-Received: from localhost ([::1]:41345 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XrqxN-0006gg-MU for ged-emacs-devel@m.gmane.org; Fri, 21 Nov 2014 11:21:13 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45182) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xrqw3-0005qZ-0m for emacs-devel@gnu.org; Fri, 21 Nov 2014 11:19:56 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xrqvx-0005FE-PY for emacs-devel@gnu.org; Fri, 21 Nov 2014 11:19:50 -0500 Original-Received: from randomsample.de ([5.45.97.173]:49694) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xrqvx-0005Eq-Gn; Fri, 21 Nov 2014 11:19:45 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=randomsample.de; s=a; h=Content-Type:MIME-Version:Message-ID:Date:References:In-Reply-To:Subject:Cc:To:From; bh=UNrtqnS39yivP3yNfaTDYuJ3kGbC71iGWwx8DbP4bI8=; b=IcDaiYQdBLn5yOFeew6gubhyvr4vx6o6I4WIU1pYEaF1lJV3Z0MMxu+QyJ8YXkefDv+KX2N6g0DTYngcQyNg6sO7ZBBZYNQVqOz10tyA9XMuzvTVUEPllfIMWgvrQNxi; Original-Received: from ip4d154d80.dynamic.kabel-deutschland.de ([77.21.77.128] helo=spaten) by randomsample.de with esmtpsa (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.80) (envelope-from ) id 1Xrqvp-0000xB-3m; Fri, 21 Nov 2014 17:19:37 +0100 In-Reply-To: <83egsw50rr.fsf@gnu.org> (Eli Zaretskii's message of "Fri, 21 Nov 2014 12:03:04 +0200") User-Agent: Gnus/5.13001 (Ma Gnus v0.10) Emacs/24.3.91 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 5.45.97.173 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:177953 Archived-At: Eli Zaretskii writes: >> From: David Engster >> Date: Wed, 19 Nov 2014 23:51:11 +0100 >> Cc: Bastien , emacs-devel@gnu.org >> >> > >> >> That's precisely what I'd drop. It's just a verbose diff. > > No, it's a summary of diffs. As such, it many times presents a > bird-eye view that is hard to grasp by looking at the diffs. Well, this is also because our commits are often too large. > It is also much shorter, so if you want to decide whether a particular > changeset is of interest, you have much less text to read. A good commit title is often enough to raise interest. This entails a location prefix to mark which area of the code is affected, so that the person who maintains that area can immediately see it, filter by it, etc. As I've said: the Changelog is not completely useless. But most of its information is automatically generated from the diff. Just go through the log and in your mind strip all the generated stuff (like filenames and affected symbols), and see what information provided by the *author* actually remains - it's usually very little, and often stating the obvious, instead of saying *why* something was done. This is not primarily the author's fault: since you have to break down your changes function by function, you often cannot really describe the broader picture these changes accomplish, so you just do the mandatory book-keeping. This makes our commit logs mostly useless for actually understanding how code evolved. You may feel differently, but keep in mind there are not many people who know the Emacs code base as well as you do. When I dig into files which are unfamiliar to me (like recently into compile.el), and hit 'l' on an annotated line, it's usually a pretty frustrating experience. I encourage anyone to browse through the commit logs from projects like Git or Linux. If people then still tell me that our style is superior, so be it. -David