On Tue, Nov 28, 2017 at 20:14:12 +0100, John Darrington wrote: > The names of the changed functions (if any) cannot be (without help from some > external program). However, to anyone who is familiar with the language of > the files concerned, this information is obvious from the diff.
Not without sufficient context. If a diff contains only lines changed in a middle of a function, then you may not know what function was actually changed. I frequently experience that problem. Usually I'm looking at the diff in a VCS, in which case obtaining additional lines of context is simple. But if I were looking at a patch file, that isn't the case. A ChangeLog is also different from a diff---in a source distribution, I expect that a ChangeLog will provide useful information. I also expect that such a distribution will not contain a diff for every change in that ChangeLog. There have been cases where I looked through a ChangeLog for a project (e.g. Emacs) having downloaded a distribution tarball rather than the actual repository. And I was searching for the name of a procedure that changed. And I found it, easily, and understood from the ChangeLog entry why the change was made, without ever having to consider a diff and try to understand what all of the surrounding code was doing. The formality and (parsable) convention is also nice. When writing commit messages, someone may or may not even mention the name of the procedure that was changed. I only recently started writing ChangeLogs in the past year or so after my experiences convinced me of its benefits. But I write them as part of my commit message. > I have had this conversation with a few people in the past, and some have > suggested "put the reason in a comment in the source code". But this > suggestion is rather naive. I agree. > So I agree with Joseph, that ChangeLog messages / commit messages should give > a high level overview (with rationale) rather than the details of what has > changed, which can be gleaned from the repository anyway. ChangeLogs also don't require special software to use. They are plain text---both human readable and easily parsable. Repositories are a binary format, and typical Unix-philosophy arguments apply. -- Mike Gerwitz Free Software Hacker+Activist | GNU Maintainer & Volunteer GPG: D6E9 B930 028A 6C38 F43B 2388 FEF6 3574 5E6F 6D05 https://mikegerwitz.com
signature.asc
Description: PGP signature
