On Sun, 7 Jan 2018, Richard Stallman wrote: > > ChangeLog format effectively doubles the time required to implement > > certain kinds of changes - first you have to make the change (some > logical > > change involving many repetitive edits to many entities), then repeat the > > description for each individual edit in a way that's often more verbose > > than the diffs themselves. > > Could you show what you mean by "repeat the description for each > individual edit"? I don't think we do that. Normally when several > entities are changed in the same way, we give the description of that change > only once, after the names of all the enties that were changed. > Or we say "likewise".
Well, the changes are typically similar, but not similar enough for a single description to be accurate for every changed entity without producing very strained descriptions. Here's an example, from glibc commit 37825319ee64d51bf8b1774f4964e9743eaf5ef6, "Refactor i386 libm code forcing underflow exceptions.". 2015-09-24 Joseph Myers <[email protected]> * sysdeps/i386/fpu/i386-math-asm.h (DEFINE_LDBL_MIN): New macro. (FLT_CHECK_FORCE_UFLOW): Likewise. (DBL_CHECK_FORCE_UFLOW): Likewise. (FLT_CHECK_FORCE_UFLOW_NARROW): Likewise. (DBL_CHECK_FORCE_UFLOW_NARROW): Likewise. (LDBL_CHECK_FORCE_UFLOW_NONNEG_NAN): Likewise. (FLT_CHECK_FORCE_UFLOW_NONNAN): Likewise. (DBL_CHECK_FORCE_UFLOW_NONNAN): Likewise. (FLT_CHECK_FORCE_UFLOW_NONNEG): Likewise. (DBL_CHECK_FORCE_UFLOW_NONNEG): Likewise. (LDBL_CHECK_FORCE_UFLOW_NONNEG): Likewise. * sysdeps/i386/fpu/e_asin.S: Include <i386-math-asm.h>. (dbl_min): Replace with use of DEFINE_DBL_MIN. (__ieee754_asin): Use DBL_CHECK_FORCE_UFLOW. * sysdeps/i386/fpu/e_asinf.S: Include <i386-math-asm.h>. (flt_min): Replace with use of DEFINE_FLT_MIN. (__ieee754_asinf): Use FLT_CHECK_FORCE_UFLOW. * sysdeps/i386/fpu/e_atan2.S: Include <i386-math-asm.h>. (dbl_min): Replace with use of DEFINE_DBL_MIN. (__ieee754_atan2): Use DBL_CHECK_FORCE_UFLOW_NARROW. * sysdeps/i386/fpu/e_atan2f.S: Include <i386-math-asm.h>. (flt_min): Replace with use of DEFINE_FLT_MIN. (__ieee754_atan2f): Use FLT_CHECK_FORCE_UFLOW_NARROW. * sysdeps/i386/fpu/e_atanh.S: Include <i386-math-asm.h>. (dbl_min): Replace with use of DEFINE_DBL_MIN. (__ieee754_atanh): Use DBL_CHECK_FORCE_UFLOW_NONNEG. * sysdeps/i386/fpu/e_atanhf.S: Include <i386-math-asm.h>. (flt_min): Replace with use of DEFINE_FLT_MIN. (__ieee754_atanhf): Use FLT_CHECK_FORCE_UFLOW_NONNEG. * sysdeps/i386/fpu/e_exp2l.S: Include <i386-math-asm.h>. (ldbl_min): Replace with use of DEFINE_LDBL_MIN. (__ieee754_exp2l): Use LDBL_CHECK_FORCE_UFLOW_NONNEG_NAN. * sysdeps/i386/fpu/e_expl.S: Include <i386-math-asm.h>. [!USE_AS_EXPM1L] (cmin): Replace with use of DEFINE_LDBL_MIN. (IEEE754_EXPL): Use LDBL_CHECK_FORCE_UFLOW_NONNEG. * sysdeps/i386/fpu/s_atan.S: Include <i386-math-asm.h>. (dbl_min): Replace with use of DEFINE_DBL_MIN. (__atan): Use DBL_CHECK_FORCE_UFLOW. * sysdeps/i386/fpu/s_atanf.S: Include <i386-math-asm.h>. (flt_min): Replace with use of DEFINE_FLT_MIN. (__atanf): Use FLT_CHECK_FORCE_UFLOW. * sysdeps/i386/fpu/s_expm1.S: Include <i386-math-asm.h>. (dbl_min): Replace with use of DEFINE_DBL_MIN. (__expm1): Use DBL_CHECK_FORCE_UFLOW. Move underflow check after main computation. * sysdeps/i386/fpu/s_expm1f.S: Include <i386-math-asm.h>. (flt_min): Replace with use of DEFINE_FLT_MIN. (__expm1f): Use FLT_CHECK_FORCE_UFLOW. Move underflow check after main computation. * sysdeps/i386/fpu/s_log1p.S: Include <i386-math-asm.h>. (dbl_min): Replace with use of DEFINE_DBL_MIN. (MO): New macro. (__log1p): Use MO. Use DBL_CHECK_FORCE_UFLOW_NONNAN. * sysdeps/i386/fpu/s_log1pf.S: Include <i386-math-asm.h>. (flt_min): Replace with use of DEFINE_FLT_MIN. (MO): New macro. (__log1pf): Use MO. Use FLT_CHECK_FORCE_UFLOW_NONNAN. * sysdeps/i386/fpu/s_log1pl.S (MO): New macro. (__log1pl): Use MO. Note that: * There are multiple things being done in each file. These things are linked to each other, so having one block of ChangeLog entries for all "Include <i386-math-asm.h>." changes (for example) shortens things by allowing "Likewise.", but effectively obscures how that inclusion is linked to the other changes within each file changed. * The changes for float and double functions / constants are slightly different. Furthermore, there are several different checking macros used in different functions, so to use a single message that applies in each case it would need to be something vaguer like "Use appropriate checking macros.". * There are other differences in particular cases, such as "Move underflow check after main computation.". This sort of thing - where changes are repetitive, but not quite repetitive enough for a single description to readily be accurate for all of a group of related changes - is common in glibc, because of how there are often multiple similar but non-identical system-specific implementations of given functionality (or as in the above example, implementations of floating-point functions for different floating-point types and formats). By comparison, I think the changeset-level log for that commit is much more helpful to understanding it, and that given that overall description, the diffs suffice if someone wants more detailed information. commit 37825319ee64d51bf8b1774f4964e9743eaf5ef6 Author: Joseph Myers <[email protected]> Date: Thu Sep 24 21:41:00 2015 +0000 Refactor i386 libm code forcing underflow exceptions. This patch refactors code in sysdeps/i386/fpu that forces underflow exceptions to use common macros for that purpose as far as possible. (Although some of the macros end up used in only one place, I think it's cleanest to define all these macros together so that all the code forcing underflow uses such macros. Some more uses of such macros will also be introduced when fixing remaining bugs about missing underflow exceptions, and it would be possible to do further refactoring of the macros in i386-math-asm.h to share more code by using other macros internally. Places that test for underflow by examining the representation of the argument with integer operations, rather that using floating-point comparisons on the argument or result, are unchanged by this patch.) Most of this code uses a macro MO to abstract away the differences between PIC and non-PIC memory references to constants. log1p functions, however, hardcoded PIC conditionals for this. Because the common macros rely on the use of MO, I changed the log1p functions to use the normal style here, and, for consistency, also made that change to log1pl which is otherwise unaffected by this patch. Tested for x86. -- Joseph S. Myers [email protected]
