Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[Glenn Morris]

David Kastrup wrote:

> branch: master
> commit 5022e27dac4c13651941e425dbec5b3a2cecdae4
> Author: David Kastrup <dak@gnu.org>
> Commit: David Kastrup <dak@gnu.org>
>
>     ; Do not overwrite preexisting contents of unread-command-events

Surely this change deserved to create a ChangeLog entry, rather than
being marked with "; " to exclude that.

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[David Kastrup]

Glenn Morris <rgm@gnu.org> writes:

> David Kastrup wrote:
>
>> branch: master
>> commit 5022e27dac4c13651941e425dbec5b3a2cecdae4
>> Author: David Kastrup <dak@gnu.org>
>> Commit: David Kastrup <dak@gnu.org>
>>
>>     ; Do not overwrite preexisting contents of unread-command-events
>
> Surely this change deserved to create a ChangeLog entry, rather than
> being marked with "; " to exclude that.

It's a sort of a janitorial potential bug fix for symptoms nobody
complained about yet, distributed around dozens of files and disparate
functions in various parts of Emacs.  I've posted the patch more than a
week ago on emacs-devel.  No comment.  I put out a reminder yesterday
that I was going to push this patch.  No comment.

A ChangeLog entry would run over several dozens of lines and take the
better part of an hour to create since C-x v a does not work with Git.
I figured that nobody would even notice anyway.

What do you propose I do now?

-- 
David Kastrup

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Glenn Morris <rgm@gnu.org> writes:
>
>> David Kastrup wrote:
>>
>>> branch: master
>>> commit 5022e27dac4c13651941e425dbec5b3a2cecdae4
>>> Author: David Kastrup <dak@gnu.org>
>>> Commit: David Kastrup <dak@gnu.org>
>>>
>>>     ; Do not overwrite preexisting contents of unread-command-events
>>
>> Surely this change deserved to create a ChangeLog entry, rather than
>> being marked with "; " to exclude that.
>
> It's a sort of a janitorial potential bug fix for symptoms nobody
> complained about yet, distributed around dozens of files and disparate
> functions in various parts of Emacs.  I've posted the patch more than a
> week ago on emacs-devel.  No comment.  I put out a reminder yesterday
> that I was going to push this patch.  No comment.
>
> A ChangeLog entry would run over several dozens of lines and take the
> better part of an hour to create since C-x v a does not work with Git.
> I figured that nobody would even notice anyway.
>
> What do you propose I do now?

That question was not rhetorical.  I admit that the leadup may not have
been the best incentive for answering it.  Sorry for that.  What I was
saying was that my own judgment was that the next consistent option
would have been a significant investment of effort that I saw no
compelling justification for, so I shopped for other opinions without
result.

You disagree, but I don't see your take on "next consistent option".
I am not opposed to investing a significant additional amount of time
for meeting a reasonable project objective.  But I don't want to waste
that time based on guesswork that might end wide off the mark.

-- 
David Kastrup

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Sat, 08 Aug 2015 10:33:17 +0200
> Cc: emacs-devel@gnu.org
> 
> > What do you propose I do now?
> 
> That question was not rhetorical.

It's unclear to me what exactly were you asking.  If the question is
how to fix that single ChangeLog entry, then the answer is: wait for
the update to ChangeLog.2 to be committed (happens once a week, I
think), and then manually correct (add in your case) the problematic
entry, and commit the result.

If you are asking about future log entries, then here's what I do: I
keep a local ChangeLog file, which is unversioned.  I use the normal
"C-x 4 a" command to write a ChangeLog entry, and then I copy it to
the log message when I commit the changeset.

If the question is how to format the log entry for the particular
changeset you committed in 5022e27dac4c13651941e425dbec5b3a2cecdae4,
then after looking through it I see no problem to just mention every
function where you made the changes.  It sounds like most of them
replace setq with a push, or do similar minor changes, which is fine
to mention in the log entry.

HTH

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Sat, 08 Aug 2015 10:33:17 +0200
>> Cc: emacs-devel@gnu.org
>> 
>> > What do you propose I do now?
>> 
>> That question was not rhetorical.
>
> It's unclear to me what exactly were you asking.  If the question is
> how to fix that single ChangeLog entry, then the answer is: wait for
> the update to ChangeLog.2 to be committed (happens once a week, I
> think), and then manually correct (add in your case) the problematic
> entry, and commit the result.

Well, the question is just what this entry should entail.  Every changed
function and file?  That will be a rather large entry.

Apart from that I don't think I need to "wait for the update to
ChangeLog.2" since the complaint was that the log message was formatted
in a way where it would not even cause an entry to ChangeLog.2.  So it
doesn't really seem to matter all that much just when I'll update
ChangeLog.2 manually.

> If you are asking about future log entries, then here's what I do: I
> keep a local ChangeLog file, which is unversioned.  I use the normal
> "C-x 4 a" command to write a ChangeLog entry, and then I copy it to
> the log message when I commit the changeset.

After unindenting and reformatting, yeah.  Which is a total crutch.  But
it's not like I haven't done it for years just like that.  I just
pointed out that this will lead to a very large ChangeLog entry here.

> If the question is how to format the log entry for the particular
> changeset you committed in 5022e27dac4c13651941e425dbec5b3a2cecdae4,
> then after looking through it I see no problem to just mention every
> function where you made the changes.  It sounds like most of them
> replace setq with a push, or do similar minor changes, which is fine
> to mention in the log entry.

Well, the changes are mostly of the "similar minor change" kind, namely
not completely obeying the same description.

The main problem I have is that the invested work and the resulting
space in the ChangeLog is not going to save anybody any time or effort
since we are not talking about a feature here or normally user-visible
changes in semantics.  And it's not particular to any package/feature
either.  It's not the kind of change we are maintaining a ChangeLog file
separate from commit messages for.

I can invest the time necessary for creating this dump half-manually if
desired.  I just have a trouble figuring out any reason why it would be
desired.  If we had an automated way of creating such a change log entry
generating commit message, it would waste less of the _writer's_ time.
But I can't help the feeling that in this case I'm also only wasting
_readers'_ time.

The reason I made that simple commit message really wasn't "oh, I'm too
lazy to do a proper one" but rather "this would not even make sense".
Obviously other developers disagree after the fact so I'll "fix" it.  I
just have a hard time doing a fix that does not feel like making the
situation worse than it is already.

-- 
David Kastrup

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Cc: rgm@gnu.org,  emacs-devel@gnu.org
> Date: Sat, 08 Aug 2015 11:38:32 +0200
> 
> Well, the question is just what this entry should entail.  Every changed
> function and file?

Yes.

> That will be a rather large entry.

It's not a problem.  We have our share of such large entries already.

> Apart from that I don't think I need to "wait for the update to
> ChangeLog.2" since the complaint was that the log message was formatted
> in a way where it would not even cause an entry to ChangeLog.2.  So it
> doesn't really seem to matter all that much just when I'll update
> ChangeLog.2 manually.

Right.

> Well, the changes are mostly of the "similar minor change" kind, namely
> not completely obeying the same description.

Nevertheless, I think it should be possible to come up with some text
that would allow you to have a single entry for all of those changes.

> The main problem I have is that the invested work and the resulting
> space in the ChangeLog is not going to save anybody any time or effort
> since we are not talking about a feature here or normally user-visible
> changes in semantics.  And it's not particular to any package/feature
> either.  It's not the kind of change we are maintaining a ChangeLog file
> separate from commit messages for.

I think our rule is to have ChangeLog entries for all non-trivial
changes whose description carries significant information.  Basically,
anything that people might want looking up in order to understand why
was the change done.  I think your changes qualify.

> The reason I made that simple commit message really wasn't "oh, I'm too
> lazy to do a proper one" but rather "this would not even make sense".
> Obviously other developers disagree after the fact so I'll "fix" it.  I
> just have a hard time doing a fix that does not feel like making the
> situation worse than it is already.

Something like this:

  * file1 (func1, func2, func3):
  * file2 (func4, func5):
  * file3 (func6, func7, func8, func9): Minor improvements in how
  events are added to unread-command-events.

shouldn't make things worse, and should be fairly easy to write, I
think.

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[Stefan Monnier]

>>> Surely this change deserved to create a ChangeLog entry, rather than
>>> being marked with "; " to exclude that.
>> A ChangeLog entry would run over several dozens of lines and take the
>> better part of an hour to create since C-x v a does not work with Git.
>> I figured that nobody would even notice anyway.

I think what Glenn said, was that the entry should not have started with
";".  That would have generated a sub-optimal ChangeLog entry, but
that's better than no ChangeLog entry.


        Stefan

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[David Kastrup]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>>>> Surely this change deserved to create a ChangeLog entry, rather than
>>>> being marked with "; " to exclude that.
>>> A ChangeLog entry would run over several dozens of lines and take the
>>> better part of an hour to create since C-x v a does not work with Git.
>>> I figured that nobody would even notice anyway.
>
> I think what Glenn said, was that the entry should not have started
> with ";".  That would have generated a sub-optimal ChangeLog entry,
> but that's better than no ChangeLog entry.

Let me make very clear that I looked at CONTRIBUTE first and finally
went by

- Start with a single unindented summary line explaining the change;
  do not end this line with a period.  If that line starts with a
  semi-colon and a space "; ", the log message will be ignored when
  generating the ChangeLog file.  Use this for minor commits that do
  not need separate ChangeLog entries, such as changes in etc/NEWS.

since the only listed alternative was a full GNU-style ChangeLog commit
message.  Without looking at CONTRIBUTE, I would have written up a
commit message like I do on other projects, _not_ listing every filename
and function name (which are listed in the accompanying context diff
"git log -p" produces).  That would have been little work and would have
made every bit of information readily accessible that one would want.

I was not sure that the ChengeLog-entry free variant was really the best
choice.  That's one of the reason I posted the patch for comment on the
Emacs-devel list.

I'll prepare a ChangeLog entry like Eli described and commit it.
I really cannot imagine that it will be useful ever to anybody as the
collection of function names and affected files is a rather random
assortment (I could not name a single one in spite of creating the
patch).  So I skipped out on work I could not imagine anyone to want.
I was wrong on that but in my defense I did solicit for feedback.

-- 
David Kastrup

Re: master 5022e27: ; Do not overwrite preexisting contents of unread-command-events

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
>
>>>>> Surely this change deserved to create a ChangeLog entry, rather than
>>>>> being marked with "; " to exclude that.
>>>> A ChangeLog entry would run over several dozens of lines and take the
>>>> better part of an hour to create since C-x v a does not work with Git.
>>>> I figured that nobody would even notice anyway.
>>
>> I think what Glenn said, was that the entry should not have started
>> with ";".  That would have generated a sub-optimal ChangeLog entry,
>> but that's better than no ChangeLog entry.
>
> Let me make very clear that I looked at CONTRIBUTE first and finally
> went by
>
> - Start with a single unindented summary line explaining the change;
>   do not end this line with a period.  If that line starts with a
>   semi-colon and a space "; ", the log message will be ignored when
>   generating the ChangeLog file.  Use this for minor commits that do
>   not need separate ChangeLog entries, such as changes in etc/NEWS.
>
> since the only listed alternative was a full GNU-style ChangeLog commit
> message.  Without looking at CONTRIBUTE, I would have written up a
> commit message like I do on other projects, _not_ listing every filename
> and function name (which are listed in the accompanying context diff
> "git log -p" produces).  That would have been little work and would have
> made every bit of information readily accessible that one would want.
>
> I was not sure that the ChengeLog-entry free variant was really the best
> choice.  That's one of the reason I posted the patch for comment on the
> Emacs-devel list.
>
> I'll prepare a ChangeLog entry like Eli described and commit it.
> I really cannot imagine that it will be useful ever to anybody as the
> collection of function names and affected files is a rather random
> assortment (I could not name a single one in spite of creating the
> patch).  So I skipped out on work I could not imagine anyone to want.
> I was wrong on that but in my defense I did solicit for feedback.

Committed.  I should be very much surprised if this will ever prove
useful to anybody.  But at least it should close this discussion.

2015-08-04  David Kastrup  <dak@gnu.org>

	Do not overwrite preexisting contents of unread-command-events
	* lisp/vc/emerge.el (emerge-show-file-name):
	* lisp/progmodes/vhdl-mode.el (vhdl-electric-dash)
	(vhdl-comment-insert, vhdl-hooked-abbrev):
	* lisp/progmodes/octave.el (inferior-octave-dynamic-list-input-ring):
	* lisp/progmodes/fortran.el (fortran-window-create-momentarily):
	* lisp/progmodes/ebrowse.el (ebrowse-hack-electric-buffer-menu):
	* lisp/progmodes/cperl-mode.el (cperl-putback-char):
	* lisp/obsolete/vip.el (vip-escape-to-emacs)
	(vip-prefix-arg-value, vip-prefix-arg-com):
	* lisp/obsolete/terminal.el (te-escape-extended-command-unread):
	* lisp/leim/quail/tibetan.el (quail-tibetan-update-translation)
	(quail-tibkey-update-translation):
	* lisp/leim/quail/lrt.el (quail-lrt-update-translation):
	* lisp/leim/quail/lao.el (quail-lao-update-translation):
	* lisp/leim/quail/japanese.el (quail-japanese-update-translation)
	(quail-japanese-self-insert-and-switch-to-alpha):
	* lisp/leim/quail/hangul.el (hangul2-input-method)
	(hangul3-input-method, hangul390-input-method):
	* lisp/language/hanja-util.el (hangul-to-hanja-char):
	* lisp/international/robin.el (robin-input-method):
	* lisp/international/quail.el (quail-start-translation)
	(quail-start-conversion):
	* lisp/gnus/gnus-art.el (gnus-article-describe-key)
	(gnus-article-describe-key-briefly):
	* lisp/eshell/em-hist.el (eshell-list-history):
	* lisp/term.el (term-dynamic-list-input-ring)
	(term-dynamic-list-completions):
	* lisp/subr.el (momentary-string-display):
	* lisp/simple.el (read-quoted-char):
	* lisp/pcomplete.el (pcomplete-show-completions):
	* lisp/kmacro.el (kmacro-repeat-on-last-key):
	* lisp/info.el (Info-summary):
	* lisp/ehelp.el (electric-help-command-loop):
	* lisp/ebuff-menu.el (electric-buffer-list)
	(Electric-buffer-menu-exit):
	* lisp/double.el (double-translate-key):
	* lisp/comint.el (comint-dynamic-list-input-ring)
	(comint-dynamic-list-completions): Do not overwrite preexisting
	contents of `unread-command-events' when putting new events into
	it.

-- 
David Kastrup