From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: git history tracking across renames (and emacs support) (Was: The name gnus-cloud.el) Date: Sun, 07 Jan 2018 21:16:57 -0500 Message-ID: References: <87bmj6dda0.fsf@linux-m68k.org> <87vahe911g.fsf@lifelogs.com> <87374id7jy.fsf@linux-m68k.org> <877ett8g7k.fsf@lifelogs.com> <87a7yn7tqp.fsf@lifelogs.com> <878te75xa1.fsf@lifelogs.com> <87ind6l2tt.fsf@lifelogs.com> <877etklvsa.fsf@lifelogs.com> <83y3m0pv8u.fsf@gnu.org> <86608msw0h.fsf@dod.no> <838tdiet25.fsf@gnu.org> <87y3li4vh7.fsf@telefonica.net> <87efnan46u.fsf@linux-m68k.org> <86wp12qtgo.fsf@dod.no> <83tvw6chqv.fsf@gnu.org> <86shbprix7.fsf_-_@dod.no> Reply-To: rms@gnu.org NNTP-Posting-Host: blaine.gmane.org Content-Type: text/plain; charset=Utf-8 X-Trace: blaine.gmane.org 1515377781 5396 195.159.176.226 (8 Jan 2018 02:16:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 8 Jan 2018 02:16:21 +0000 (UTC) Cc: sb@dod.no, emacs-devel@gnu.org To: Paul Eggert Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 08 03:16:17 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eYMyx-0000gL-0z for ged-emacs-devel@m.gmane.org; Mon, 08 Jan 2018 03:16:11 +0100 Original-Received: from localhost ([::1]:57782 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eYN0w-0005sE-5D for ged-emacs-devel@m.gmane.org; Sun, 07 Jan 2018 21:18:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44732) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eYN09-0005ry-1B for emacs-devel@gnu.org; Sun, 07 Jan 2018 21:17:25 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eYN08-0001tW-0t for emacs-devel@gnu.org; Sun, 07 Jan 2018 21:17:25 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:52889) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eYMzh-0001if-QR; Sun, 07 Jan 2018 21:16:57 -0500 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1eYMzh-0004kS-Ah; Sun, 07 Jan 2018 21:16:57 -0500 In-reply-to: (message from Paul Eggert on Tue, 2 Jan 2018 00:06:11 -0800) 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:221698 Archived-At: [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > What would be most helpful (and I realize I'm asking for a lot) would be > ChangeLog entries or commit messages (it doesn't matter which) that explain the > *motivation* for each change. Our current practice is to put the explanation into comments in the code. I think that makes it moe visible than in the history. If you think it is better to put the explanation in the history? could you explain what advantage you see? You later wrote > Yes, that is preferable if it makes sense in the new > code. However, it often doesn't make sense. For example, when > deleting a file one typically does not want to leave a message > behind where the file used to be, saying "this file was deleted", > as that would just slow down later maintainers who normally > shouldn't Indeed, you can't put a message in a deleted file. But if that file was not disused, I presume the same change includes code in other files. That's the best place to put the explanation. But if there is no natural place for the explanation in the source code, you should put it in the history. If that's not clear enough now, we can make it clearer. ====================================================================== For changes to code, there's no need to describe the full purpose of the changes or how they work together. If you think that a change calls for explanation, you're probably right. Please do explain it---but please put the full explanation in comments in the code, where people will see it whenever they see the code. For example, ``New function'' is enough for the change log when you add a function, because there should be a comment before the function definition to explain what it does, how to call it, and so on. For changes to files that do not support a comment syntax (e.g., media files), it is ok to include the full explanation in the change log file, after the title and before the list of individual changes. ====================================================================== -- Dr Richard Stallman President, Free Software Foundation (https://gnu.org, https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org) Skype: No way! See https://stallman.org/skype.html.