ChangeLog policy for same-day changes to a file?

ChangeLog policy for same-day changes to a file?

[Karl Fogel]

Notice the multiple appearances of "doc-view.el" in this single entry
from lisp/ChangeLog:

   2007-12-26  Tassilo Horn  <tassilo@member.fsf.org>

	* image-mode.el (image-bookmark-make-cell, image-bookmark-jump):
	New functions.
	(image-mode): Set bookmark-make-cell-function appropriately.

	* doc-view.el (doc-view-bookmark-jump): Correct misspelled arg name.

	* bookmark.el (bookmark-make-cell-function): New variable.
	(bookmark-make): Call bookmark-make-cell-function's function
	instead of bookmark-make-cell.
	(bookmark-get-handler, bookmark-jump-internal): New functions.
	(bookmark-jump, bookmark-jump-other-window, bookmark-insert)
	(bookmark-bmenu-2-window, bookmark-bmenu-other-window):
	Use bookmark-jump-internal.
	(bookmark-make-cell-for-text-file): Renamed from bookmark-make-cell.

	* doc-view.el (doc-view-bookmark-make-cell)
	(doc-view-bookmark-jump): New functions.
	(doc-view-mode): Set bookmark-make-cell-function buffer-locally.

Obviously, they represent separate CVS commits to doc-view.el, but on
the same day, so Tassilo put them into the same ChangeLog entry.  The
result is counterintuitive, but I'm not sure what else he should do.
Create a separate ChangeLog entry with the same date?  Do we have a
policy for how to handle this?

(I have little experience with this issue, because no other project I
work on manually maintains a ChangeLog file in addition to the log
messages stored by the version control system.)

-Karl

Re: ChangeLog policy for same-day changes to a file?

[Miles Bader]

Karl Fogel <kfogel@red-bean.com> writes:
> Obviously, they represent separate CVS commits to doc-view.el, but on
> the same day, so Tassilo put them into the same ChangeLog entry.  The
> result is counterintuitive, but I'm not sure what else he should do.
> Create a separate ChangeLog entry with the same date?  Do we have a
> policy for how to handle this?

Does it matter?  Either seems clear enough, for a human reader, at
least.

-Miles

-- 
We live, as we dream -- alone....

Re: ChangeLog policy for same-day changes to a file?

[Karl Fogel]

Miles Bader <miles@gnu.org> writes:
> Karl Fogel <kfogel@red-bean.com> writes:
>> Obviously, they represent separate CVS commits to doc-view.el, but on
>> the same day, so Tassilo put them into the same ChangeLog entry.  The
>> result is counterintuitive, but I'm not sure what else he should do.
>> Create a separate ChangeLog entry with the same date?  Do we have a
>> policy for how to handle this?
>
> Does it matter?  Either seems clear enough, for a human reader, at
> least.

It's just confusing because there is an implicit one-to-one mapping
between ChangeLog top-level entries and CVS commits.  While I can
discard this assumption if advised to, I'm pretty sure it's one many
developers would share, especially those unfamiliar with Emacs's
unusual ChangeLog policy (i.e., virtually every incoming developer).

When I read Tassilo's entry, I hit that first mention of doc-view.el
and assumed I'd seen everything Tassilo did to that file on that day.
That caused me to spend a bit of time being confused, because I knew
there should be more.  Eventually I saw what I was looking for, later
in the entry.

Personally, I'm going to make a separate top-level entry in ChangeLog
for each commit of mine.  I don't know whether I'll bother to defactor
Tassilo's entry, though ("mattress in the road" problem and all that).

-Karl

Re: ChangeLog policy for same-day changes to a file?

[Miles Bader]

Karl Fogel <kfogel@red-bean.com> writes:
>> Does it matter?  Either seems clear enough, for a human reader, at
>> least.
>
> It's just confusing because there is an implicit one-to-one mapping
> between ChangeLog top-level entries and CVS commits.

There's never been such an implicit mapping.  Perhaps it happens by
chance in many cases (often because after you've committed something,
somebody else will sneak in and put their own entry in the ChangeLog
before yours), but I regularly (on a daily basis) see counter-examples.

-Miles

-- 
Next to fried food, the South has suffered most from oratory.
  			-- Walter Hines Page

Re: ChangeLog policy for same-day changes to a file?

[Richard Stallman]

    Obviously, they represent separate CVS commits to doc-view.el, but on
    the same day, so Tassilo put them into the same ChangeLog entry.  The
    result is counterintuitive, but I'm not sure what else he should do.

This is the way we do it.
There's nothing wrong with it.

    It's just confusing because there is an implicit one-to-one mapping
    between ChangeLog top-level entries and CVS commits.

We have never made that assumption.