Re: Why are so many great packages not trying to get included in GNU Emacs? WAS: Re: Making Emacs more friendly to newcomers

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: Eli Zaretskii <eliz@gnu.org>, Dmitry Gutov <dgutov@yandex.ru>, Stefan
>       Kangas <stefan@marxist.se>, emacs-devel@gnu.org
> Date: Fri, 19 Jun 2020 01:34:21 +0300
> 
> > I’d also like to note that this list can be invaluable when rebasing
> > commits and resolving conflicts.  It’s not strictly necessary (just like
> > other parts of a version control workflow are not strictly necessary),
> > but it can serve as a sanity check in a time when the diff is not
> > authoritative as it is in flux.
> 
> While it may be useful, but explicit examples may be more interesting. Right 
> now
> when I read your text about this list in the context of resolving rebase
> conflicts, I only see the downside that if the conflict came up because a
> function was renamed, you need to go fix the commit message too.
> 
> Even worse: if upon rebasing a function was renamed, you may not get any
> conflicts (i.e. because thunk you modified didn't include the beginning of the
> function), and now your commit message is broken without you even noticing.

There's no requirement to retroactively fix commit log messages when
files or functions are renamed.  The renaming is recorded in the
history and can be found when one needs to explore the history of some
code fragment.

What is important is that the log message names the files and
functions/macros/data structures as they are called at the time of the
commit, because the log message is many times read in conjunction with
the diffs.

So I don't think the difficulties you describe are real.

> It is possible, it's just that I do not see this. Convincing someone that the
> commit message with the list provides more benefit than without it requires
> examples that make it explicit. 
> 
> So far the whole thread (both this part and the one with Dmitry) had only
> negative examples, i.e. why having the list is a burden to anyone.

The GNU Coding Standards were recently changed to provide the
rationale for having this information in the log messages.  Since the
official Prep page wasn't updated yet, I show the relevant text below,
in the hope that it will give you enough information to understand why
having that in the log messages could be beneficial.

> Let me sum up the positive mentions: so far, you just say it simplifies review
> for you, but I don't know your workflow, there may be many factors that make 
> you
> assert that, which does not necessarily applies to everyone. Dmitry said the
> list makes better commit messages from novices, but again when I tried to dig
> deeper, that discussion died.

When you contribute changes to a project, you need to satisfy the
workflows of others, even if they differ from yours.  So you need to
respect the opinions of the project developers when they tell you this
information is of help to them.

Here are the excerpts from the latest GNU Coding Standards manual I
mentioned above:

----------------------------------------------------------------------
Therefore, change logs should be detailed enough and accurate enough
to provide the information commonly required for such @dfn{software
forensics}.  Specifically, change logs should make finding answers to
the following questions easy:

@itemize @bullet
@item
What changes affected a particular source file?

@item
Was a particular source file renamed or moved, and if so, as part of
what change?

@item
What changes affected a given function or macro or definition of a
data structure?

@item
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?

@item
What changes deleted a function (or macro or data structure)?

@item
What was the rationale for a given change, and what were its main
ideas?

@item
Is there any additional information regarding the change, and if so,
where can it be found?
@end itemize
[...]
Following the free-text description of the change, it is a good idea
to give a list of names of the entities or definitions that you
changed, according to the files they are in, and what was changed in
each one.  @xref{Style of Change Logs}.  If a project uses a modern
@acronym{VCS} to keep the change log information, as described in
@ref{Change Logs}, explicitly listing the files and functions that
were changed is not strictly necessary, and in some cases (like
identical mechanical changes in many places) even tedious.  It is up
to you to decide whether to allow your project's developers to omit
the list of changed files and functions from the log entries, and
whether to allow such omissions under some specific conditions.
However, while making this decision, please consider the following
benefits of providing the list of changed entities with each change:

@itemize @bullet
@item
Generation of useful @file{ChangeLog} files from @acronym{VCS} logs
becomes more difficult if the change log entries don't list the
modified functions/macros, because @acronym{VCS} commands cannot
reliably reproduce their names from the commit information alone.  For
example, when there is a change in the header part of a function
definition, the heading of the diff hunk as shown in the VCS log
commands will name the wrong function as being modified (usually, the
function defined before the one being modified), so using those diffs
to glean the names of the modified functions will produce inaccurate
results.  You will need to use specialized scripts, such as gnulib's
@file{vcs-to-changelog.py}, mentioned below, to solve these
difficulties, and make sure it supports the source languages used by
your project.

@item
While modern @acronym{VCS} commands, such as Git's @kbd{git log -L}
and @kbd{git log -G}, provide powerful means for finding changes that
affected a certain function or macro or data structure (and thus might
make @file{ChangeLog} files unnecessary if you have the repository
available), they can sometimes fail.  For example, @kbd{git log -L}
doesn't support syntax of some programming languages out of the box.
Mentioning the modified functions/macros explicitly allows finding the
related changes simply and reliably.

@item
Some @acronym{VCS} commands have difficulties or limitations when
tracking changes across file moves or renames.  Again, if the entities
are mentioned explicitly, those difficulties can be overcome.

@item
Users that review changes using the generated @file{ChangeLog} files
may not have the repository and the @acronym{VCS} commands available
to them.  Naming the modified entities alleviates that problem.
@end itemize

@noindent
For these reasons, providing lists of modified files and functions
with each change makes the change logs more useful, and we therefore
recommend to include them whenever possible and practical.

It is also possible to generate the lists naming the modified entities
by running a script.  One such script is @file{mklog.py} (written in
Python 3); it is used by the @code{GCC} project.  Gnulib provides
another variant of such a script, called @file{vcs-to-changelog.py},
part of the @code{vcs-to-changelog} module.  Note that these scripts
currently support fewer programming languages than the manual commands
provided by Emacs (@pxref{Style of Change Logs}).  Therefore, the
above mentioned method of generating the @code{ChangeLog} file from
the @acronym{VCS} commit history, for instance via the
@code{gitlog-to-changelog} script, usually gives better
results---provided that the contributors stick to providing good
commit messages.