On Wed, 10 Jan 2018, Mike Gerwitz wrote: > Unfortunately we can't know at the time of writing a change whether > those entities might be useful in the future.
That's generically the case for any aspect of a change description. What we can judge is what's most useful for understanding the change *now*, and write that. We can also judge what's hard to reconstruct from the diff, which is generally the higher-level information, versus what could be reconstructed from the diff in future if needed, which includes the list of entities. If the average number of times a list of entities is needed is much smaller than 1 per commit (and I suspect it's much smaller, for the projects I work on), it makes more sense for the reader to construct it if needed rather than for the writer to construct such lists that will probably never be needed. > Entities are concrete, > unambiguous---you can phrase them only one way. For the example I gave of Makefile entity names involving complicated GNU make constructs, that needed to be wrapped over multiple lines, that's not the case. For cases where what's really changing is conditionals rather than entities, there's significant ambiguity about how to write them in the ChangeLog entry. [foo || bar] or [defined foo || defined bar]? Do you do "* [foo]: Remove conditional code." or list the individual entities removed within [foo]? If it's a makefile conditional, do you use [ifeq ($(foo), bar)] or [$(foo) = bar]? Where the full name of an entity is long - with namespace or class qualification, or requiring parameter types for an overloaded function - exactly what form do you use? > Trying to search through English describing a change can be very > difficult. Trying to shoehorn the cases above into ChangeLog format can be very difficult. You can produce something vaguely plausible, but there's no reason to expect that someone else would come up with the same form of the names so as to be able to search for them, or that what you've produced will be particularly useful. > for. And once I've found it, more often than not, I have to figure out the > meaning behind the diff, possibly recursively until I find the change I > need. The meaning behind the diff is what I think the commit messages should be providing - at a logical level, as appropriate to the diff in question. > But that doesn't mean that it's easy. My goal is to make life easier for > those who come after me (including the future me). I want to make life easier for developers by being able to concentrate on the changes themselves and a description at the logical, human level, without needing to spend time on a second description at a level only slightly above that of the diffs themselves, for projects where the level of ChangeLog entries is not generally the most helpful level for understanding the changes. -- Joseph S. Myers jos...@codesourcery.com