Re: ChangeLogs (was: Re: [changeset] don't remove whitespace within @example in docstrings)

[Jaroslav Hajek]

On Mon, Jan 5, 2009 at 5:32 PM, John W. Eaton <address@hidden> wrote:
> On  5-Jan-2009, Jaroslav Hajek wrote:
>
> | Applied.
>
> Thanks for applying this change.
>
> It still seems confusing to me that you leave the ChangeLog entry
> alone when applying patches.  If I do "hg log" now, I see
>
>  changeset:   8444:c3ac9f2772cd
>  tag:         tip
>  user:        Thorsten Meyer <address@hidden>
>  date:        Mon Jan 05 10:54:22 2009 +0100
>  summary:     do not eat white space within @example environments of 
> docstrings
>
> at the top, but the ChangeLog entry for this change does not have a
> Jan 5 date.  Instead, it has a 2008-11-07 date.  If I were looking at
> this ChangeLog entry and wanted to find the corresponding changeset,
> the date for the ChangeLog entry would not help me find the changeset.
> This is why I think we should revise the date of the ChangeLog entry
> when checking in changes so that new ChangeLog entries should always
> appear at the top of the ChangeLog file.
>

Well, it depends on what you expect of this changelog entry. My
understanding is that this reflects the date when the patch was
created by its author; and, presumably, posted to the mailing list. It
can be applied much later by someone else (like in this case). That
later date is reflected by the date of the mercurial changeset.
When I transplant changesets to release archive, I use -D (which I had
to implement in Mercurial) to refresh the date. The date in ChangeLog
file still reflects the date of origin of the change.
What you would like to see in ChangeLogs, i.e. the date of
application, can be generated by running "hg annotate" on the
ChangeLog file and doing a little parsing of the result.

Another merit is purely practical - with the simple "changelogmask"
extension to mercurial I've created, treating changelog entries "my
way" makes most of patches apply cleanly (those that only prepend
lines to ChangeLog files). This was a real boost in the transplanting
process - prior to that, there was a conflict for almost every
transplanted patch; now, clean application is more common. I would be
unhappy to abandon this convenient practice :(

> Or, we should simply decide to do away with ChangeLog files entirely.
> But if we do that, I think we should put much more complete commit
> messages in the mercurial log files, and we should agree on a common
> style for the commit messages.
>

Another option, if you disagree with my treating of the dates, is to
simply left them out from the changelog files. After all, "your-style
dates" can be auto-generated.
But it will be probably good if we settle on a common style.

regards

-- 
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz