Re: How can we decrease the cognitive overhead for contributors?

[Simon Tournier]

Hi,

On Tue, 05 Sep 2023 at 11:01, Katherine Cox-Buday <cox.katherine.e@gmail.com> 
wrote:

>> Well, somehow, I consider the commit message format similarly as coding
>> style.  We can discuss which one is better than the other when at the
>> end it only reflects some artificial preferences and for the sake of any
>> project one needs to be arbitrarily picked.  Why not ChangeLog?
>
> The distinction I draw is that I can usually run a linter against a
> coding style.
>
> I don't care very much what the standard for commit messages is other
> than if it has an expectation of structure, I be able to run a tool to
> tell me if it's wrong.
>
> In other words, the overhead isn't "I don't like this standard", it's "I
> can't find a way to reliably adhere to the standard".

Well, I am not sure to fully understand what you have in mind with the
term “standard“.  To me, coding style or similarly commit message format
are about standard or norm, meaning they respect a set of rules.

The question is then: is it possible to explicitly write down all the
rules?  Are all the rules all well-defined or are some ambiguous?  etc.

For some norm or standard, it is possible to have a checker because all
the rules are explicitly well-defined.  For many norms/standards, we do
not have any checker.

The current norm/standard for replying to these Guix mailing lists is
bottom-posting.  We do not have a way to reliably adhere to this
norm/standard and we are not commenting or discussing more about it.
Because this norm is easy to internalize.

Now, I have read the thread and I hear the comments about the commit
message format as ChangeLog.  To be honest, I am somehow surprised.  If
after being enough annoyed by something that then one clones the Guix
repository, finds how to improve and last drops all because writing the
commit message is too “complex” or because one does not know if the
commit message correctly adhere to the standard… Sorry, I do not buy.

And I do not buy either an issue when resuming after an interruption
because writing commit message can be done from the diff.  More than
often, I tweak stuff, then commit with the oneline subject ’DRAFT foo’,
continue to tweak, commit ’DRAFT bar’.  Days or weeks (or months) later,
I resume my work and run “git rebase” for polishing the commit ’DRAFT
foo’ and preparing it for submission.

Again I hear all the comments and I am trying hard to understand.  From
my point of view and from where I stand, my understanding is that the
core point of commit message format is about 1. discipline – the quality
of being able to behave and work in a controlled way which involves
obeying particular rules or standards – and 2. confidence – the willing
to send the perfect message on the first try.  And there is no tool for
fixing these both issues.

Example of a imperfect message:
a957171bc41e98e29674f99cf3dd2940ff45a0d3.  Typo! :-)

--8<---------------cut here---------------start------------->8---
Author:     Simon Tournier <zimon.toutoune@gmail.com>

gnu: ocaml-mdx: Fix tests.

* gnu/packages/ocaml.scm (ocaml-mdx)[arguments]: Substitue obsolete 'egrep' by
'grep -E'.

Signed-off-by: Julien Lepiller <julien@lepiller.eu>
--8<---------------cut here---------------end--------------->8---

Oops, that’s npt perfect although I did my best (proofread and
spellchecker), the patch was in the tracker for some time and I am sure
Julien carefully checked.


Yeah, commit messages are boring to write.  However, when investigating
and trying to understand some changes, it appears to me far more useful
this:

--8<---------------cut here---------------start------------->8---
ec0a2fc87bd651ebc8f253f6369ba4485912d9b2

upstream: 'update-package-source' edits input fields.

Previously, 'guix refresh r-ggplot2 -u' and similar commands would print
of list of input changes that would have to be made manually.  With this
change, 'guix refresh -u' takes care of updating input fields
automatically.

* guix/upstream.scm (update-package-inputs): New procedure.
(update-package-source): Call it when 'upstream-source-inputs' returns
true.
* guix/scripts/refresh.scm (update-package): Remove iteration over the
result of 'changed-inputs'.
* guix/import/test.scm (available-updates): Add support for input
lists.
* tests/guix-refresh.sh (GUIX_TEST_UPDATER_TARGETS): Add input list for
"the-test-package".
Make sure 'guix refresh -u' updates 'inputs' accordingly.
* doc/guix.texi (Invoking guix refresh): Mention it.
--8<---------------cut here---------------end--------------->8---

Where the diff looks like:

        5 files changed, 72 insertions(+), 45 deletions(-)
        doc/guix.texi            |  5 +++--
        guix/import/test.scm     | 13 ++++++++++-
        guix/scripts/refresh.scm | 36 -------------------------------
        guix/upstream.scm        | 56 
++++++++++++++++++++++++++++++++++++++++++++----
        tests/guix-refresh.sh    |  7 ++++--

compared to top-notch project as Julia language:

--8<---------------cut here---------------start------------->8---
sysimg: Allow loading a system image that is already present in memory (#51121)

I've written this code probably three times at this point, but for some
reason it never made it into a PR. This allows loading a system image
that has already been loaded into memory. This happen when wanting to
distribute a static or mostly-static binary of julia code where the
system image (and optionally other libraries like libjulia, etc.) are
linked directly into the main executable. It is also useful for
deployment to environments that do not have (or have incomplete) support
--8<---------------cut here---------------end--------------->8---

where the diff looks like:

        6 files changed, 45 insertions(+), 10 deletions(-)
        src/Makefile         |  2 +-
        src/init.c           |  7 +++++--
        src/julia.h          |  2 +-
        src/julia_internal.h | 11 +++++++++++
        src/processor.cpp    | 10 +++++++++-
        src/staticdata.c     | 23 ++++++++++++++++++-----

<https://github.com/JuliaLang/julia/commit/70000ac7c3d5d5f21e42555cdf99e699a246f8ec>


Well, there is no comparison about the quality between the two commits,
IMHO.  On one hand, we have an clear idea about the change and what
exactly had been modified.  On the other hand, bah one needs to be
comfortable with the code and directly jumps to the diff hunks.  Which
commit message is helping irregular contributor or newcomer?  The one
which requires to internalize some rules?  Or the one easier to type?


Well, I share various points that had been raised in this thread about
smoothing the contribution requirements.  However, I am still puzzled by
the comments about the commit message format.  Again, my inability to
understand the issue does not mean I am not hearing.


All the rules are not explicitly written, IIRC, so the most reliable way
to adhere about the standard is probably to internalize these questions:

    What changes affected a particular source file?
    Was a particular source file renamed or moved, and if so, as part of what 
change?
    What changes affected a given function or macro or definition of a data 
structure?
    Was a function (or a macro or the definition of a data structure) renamed 
or moved from another file, and if so, as part of which change?
    What changes deleted a function (or macro or data structure)?
    What was the rationale for a given change, and what were its main ideas?
    Is there any additional information regarding the change, and if so, where 
can it be found? 

    https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs

All in all, my only proposal would to have a Git pre-commit hook or some
template pasting these questions and recalling the generic ChangeLog
format, when writing the commit message.  Maybe it would help…


Cheers,
simon