On Fri, 28 Jul 2017, Alfred M. Szmidt wrote: > > 1. The package has a public version control system. > > > > (Rationale: this ensures people can see what changed, just as with > > ChangeLogs, but can see *exactly* what changed rather than just the > > brief descriptions.) > > > > I think that rationale is incorrect, just because you have a public > > version control system does not mean that you can see what actually > > changed. Going through multiple megabytes of diffs is not feasible, > > and searching for when something was renamed, added, removed, etc is > > something no tool is capable of providing. > > That's a function of a busy project and is the same whether you look at > commit logs, diffs or ChangeLog messages. > > That doesn't address how you go through a diff to see when a function > was added/removed/renamed/moved/..., neither diff nor annotate do > those things -- nor can they in the general case. Think non-C
Check for appropriate regular expressions in the diffs. In the simple sorts of cases that the ChangeLog format can readily describe, such regular expressions will also work reasonably reliably. In more complicated cases, they may not, but the more complicated cases also aren't well-described in terms of individual named entities as required in ChangeLog format. > language, weird configuration files, etc. And they are still not Non-C languages are also a case that often doesn't work well with ChangeLog format - consider e.g. a C++ member function where identifying it for the ChangeLog requires a long fully-qualified name, complete with argument types to identify which overload is being modified. > available in binary packages or tarball releases. Binary releases likely don't include the ChangeLogs anyway. E.g. Ubuntu ships only the NEWS file with binary releases, not the ChangeLogs; likewise a CentOS system I have to hand. I think of tarball releases as just being one output of the development process. They are an essential output - to define immutably the contents of a particular version number, in the same way for everyone, so everyone can get that version and reproducibly get the same sources, do a reproducible build and get the same binaries - but I don't think we should expect much visibility into the development process from them. Understanding the development process requires many other sources of information, such as the version control history, the mailing list archives, the issue tracker, .... > I wouldn't object to shipping the version control history in tarballs, if > necessary to stop having to write in the ChangeLog format (or having > tarballs with and without the version control history). > > That would ballon the tarball so much that it would be unacceptable, > emacs has a .git directory that is around 1.8G on my machine, glibc > would be 400M with .git and all source files. A freshly packed glibc checkout (git remote prune origin; git reflog expire --expire=now --all; git gc --prune=all --aggressive) takes about 130 MB for the .git directory, and I end up with a .tar.xz of about 135 MB. Of course that includes all branches, and with just the history in the ancestry of the release in question it would be a bit smaller. And the -with-history.tar.xz could be separate from the normal version, since it's just a backup of the VCS data in case the VCS data is otherwise somehow lost (which is a lot less likely with a distributed VCS than a centralized one). > But I believe that people wanting to look at the history are going > to check out the repository rather than attempting to get it from > tarballs. > > I can only speak from my own experience, but I always persue the > ChangeLog file first. Only when a project is badly maintained do I go > for the VCS. I look at the VCS first, at least when a distributed VCS is in use so I don't need to wait for the VCS server for each log inspection. I used to look at ChangeLogs, but that's now a pretty old-fashioned, GNU-specific appproach. > I am having a hard time taking the "completely useless", "waste of > time" argument seriously when the ChangeLog files (be it in VCS, or a > file) are infact used to do exactly that: to understand how code moves > in a project. If they where so useless and waste full then most GNU > projects would have abandoned them many many years ago, and yet we > still use them very activley, even in gcc and glibc being just two > examples. They're created in GCC and glibc because the GNU Coding Standards require them, not because (in the context of having VCS history, mailing list archives, issue trackers, etc. to provide a much richer understanding of the development history relevant to any particular issue) they are useful for something not covered by those other sources of information. > This is what I would have done, you have only 8 specific changes > touching multiple files, there is no need to repeat them several times > and one could even reduce this a bit further by merging the file lines > into one. You can even skip the "Likewise." part completely. I don't think this is any better. If anything it obscures the essential nature of the change, which is very much "take each relevant file, apply this class of fixes to it", where links between identifiers of the same name in different files are entirely incidental. > Writing accurate, and descriptive ChangeLogs is just like writing > accurate documentation, both can be wrong, but so can code. This > falls onto the maintainer to see that all things are good. Just using > VCS won't solve that. The VCS history is automatically a completely accurate record of the history of the code in a way that the ChangeLogs aren't. > The point of the VCS is to be able to undo changes. ChangeLog files, and > the form of change description therein, are in no way a substitute for the > VCS, and are essentially obsoleted by it. > > The ChangeLog is for human consumption, to understand how the code was > changed, VCS does not solve this, not everything is prettily managed That understanding effectively requires the tools such as VCS, mailing lists, issue trackers etc. that give a rich structure to the history information. For users, we have the NEWS file. For people looking at how things changed at the development level, a natural process is: look at the VCS logs (describing changes logically rather than physically), then potentially delve into diffs, list archives, issue trackers, etc. for individual changes that seem of interest. > Why do you think that the ChangeLog can't mention the above? Or maybe The problem isn't that it can't mention the logical nature of the change. The problem is that given the logical description, in the VCS log, and given the diffs themselves, in the VCS history, and given the mailing list archives, bug tracker, etc. that also form part of the development process, writing a second description of the change, decomposed into descriptions at the level of individual named entities in individual files, has net negative utility; any benefit where someone is interested in that very specific level of information (for a change that doesn't map well onto that level of information) is outweighed by the extra work involved in writing that description of extremely niche use, by the time it takes away from substative development and writing descriptions at the logical level, and by putting off free software developers because of the need to jump through this hoop not needed for non-GNU projects. > better yet, since this is a bug fix in a BUGS file or similar. glibc has automatically-generated lists of fixed bugs in each release created from Bugzilla data just before the release and inserted in the NEWS file. > Neither of those are available in tarballs, nor might they be As I said, I think tarballs are just one output of the development process. It's not appropriate to expect that the rich data of the interactions involved on mailing lists, issue trackers, patch review systems, version control, etc. can be adequately serialized into or understood through a ChangeLog; a proper understanding of the development process requires using those other tools. > available in distribution packages where putting up a copy of > ChangeLog can be very useful as well even if you do not have access to In practice distribution packages likely do not include ChangeLogs. > source code. The NEWS file does not describe code changes, only > user-visible changes, so it is not very useful if you are infact > looking for a problem in a new release. The expectation is to look at VCS logs and use tools such as "git bisect". (Which could be used to look for e.g. when a function moved, if desired, not just to test properties of the compiled code.) -- Joseph S. Myers [email protected]
