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: rekado@elephly.net, joaotavora@gmail.com, dgutov@yandex.ru,
>  stefan@marxist.se,  emacs-devel@gnu.org
> Date: Sat, 20 Jun 2020 16:07:54 +0300
> 
> > 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.
> 
> Are you saying that wrong commit messages are okay?

Of course not.

> Will it be okay if I make a
> v1 of a patch where just one function is changed, and then in v2 I 
> additionally
> modify a dozen of others, and won't add their names to the commit message?

Of course not.  But you could omit the log messages completely in v1
if it is known in advance that there will be a v2.  IOW, the only log
message that really matters is the last one, the one that is going to
be committed to upstream.

It's similar to documentation: it is perfectly acceptable to initially
post a patch without the documentation bits, saying you will provide
one when the code details are finalized.

> Also, what you say here contradicts to your quote of GNU standard, which says
> the list is needed to generate Changelog files. Because not fixing commit
> messages retroactively will result in wrong Changelogs.
> 
> What's the point in wrong Changelog files and wrong commit messages?

We are miscommunicating.  You have only a very specific scenario in
mind, whereas I was talking about something much more general.  For
the situations you had in mind (IIUC), only the last variant of the
log messages matters.  If you can get those log message right on the
first attempt, you can omit them in intermediate variants, and just
say you will provide them with the last version.  (Of course, if you
don't get them right the first time, you will get review comments for
them, so it's up to you to decide whether indeed you can afford
omitting them from intermediate versions.)

Also, let's face it: changesets where v2 renames many symbols present
in v1's log are rare.  There's no need to make these rare cases sound
as if they were the rule: they are not.

> Now let's get back to Emacs. I hope it's unquestionable that purpose of Emacs
> project is prosperity of Emacs project. It doesn't have explicit purpose to
> cater to Emacs contributors or developers. But if you ask "how can we make 
> Emacs
> evolve and prosper", the "making Emacs contributors, developers and users
> comfortable" is hopefully an obvious answer.
> 
> Having good developer practices is an implication of "making
> developers/contributors comfortable". Which includes, that if some developer
> practice (I'm pointing out here to the functions list) 1. carries burden on
> everyone, and 2. Makes happy only a few (perhaps, because of their habits or
> whatever), we should ditch this practice.

We are not asking contributors to adhere to some arbitrary and
outlandish standards and practices, or something that satisfies only a
small group of people who usurped the power, so to say.  These are
standards common to the GNU Project as a whole (although minor
variations do exist, and when I submit changes to, say, GDB, I need to
do that according to what GDB developers expect and require, not to
what I'm accustomed to in Emacs).  These standards are the result of
quite a few discussions among developers of many GNU projects, where
arguments not unlike those you present are also voiced and considered.
The result is described in the GCS document, and it includes
rationale that also comes out of those discussions.

IOW, it isn't like some band of people conquered the Emacs project and
now dictates its arbitrary demands to the community at large.  These
requirements are the result of many discussions, and include the
summary experience and knowledge of many people who understand very
well that every additional requirement adds to the burden of the
contributors.

Requirements for contributors are always a fine balancing act, whereby
too few or too many requirements will both produce sub-optimal results
for various reasons.  So let's not pretend that dropping important
requirements to make it easy on contributors is the right solution,
because the requirements are there for a reason, and dropping any one
of them brings a disadvantage.  We need to carefully weigh the
advantages and disadvantages of each requirement.

> > Here are the excerpts from the latest GNU Coding Standards manual I
> > mentioned above:
> > […snipped…]
> 
> Thanks. I should say, it's a big text, half of which basically says "it's cool
> to have" which doesn't answer the question "why". So, I'm sorry if I missed 
> some
> point while reading this, in this case pointing this out more explicitly might
> help.

Actually, the reasons (a.k.a. "why") are presented there at least
twice: once indirectly, by explaining the general purpose of good
change log records, and then once more by providing specific
considerations for keeping the information we are talking about (names
of files and functions/macros/data structures that were modified) in
the log.

> 1. The list is used to generate Changelogs.

No.  The text says that it is recommended to have ChangeLog files in
the release tarball, but it doesn't make that mandatory.

> 2. The standard does not enforce having the list in commit messages if you're
> using a decent VCS (which I'd think includes git)

No.  The text leaves this decision to each package maintainer, and
presents important considerations that could and should influence that
decision.

> The text then goes into details that generating Changelogs from a VCS alone 
> may
> be unreliable. The example it shows can be reproduced on Emacs repo as 
> follows:
> if you do `git log -1 -p 50a0126402d`, you'll see some renames, however the
> context above the hunk shows not the variable/function being renamed.
> 
> I'd argue it would be way more productive to make git produce what Changelog
> files need correctly rather than forcing tedious manual work upon everybody. 
> git
> already can recognize the context correctly, we just need a specific flag to
> only make it show changed functions/variables (ATM it seems not to have it, at
> least I didn't find one).

I encourage you to talk to Git developers so that they improve this
capability.  Not sure this is going to happen in practice (knowing how
the diffs are generated, and given that one GNU project using Git
after another sets up alternative tools for overcoming these
problems), but it definitely cannot harm, so by all means go for it.