Re: Using VC for change descriptions

[Joseph Myers]

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  <address@hidden>

        * 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 <address@hidden>
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
address@hidden