Re: should changelogs be in chronological order

[Jay Berkenbilt <ejb@ql.org>]

Anthony Towns <aj@azure.humbug.org.au> writes:

> Matthew Dempsky wrote:
>> Anthony Towns <aj@azure.humbug.org.au> writes:
>>>Travis Crump wrote:
>>>>Should changelogs be in chronological order or should they be in
>>>>version number order?
>>>The changelog should be in the order changes were made.
>> Isn't that necessarily chronological order?
>
> Not if you're merging two branches, and reusing the changelogs to
> describe the (merged) changes.
>
> Well, you could still call that chronological order, but the
> chronology wouldn't necessarily match the dates listed in the
> changelog.
>
> Cheers,
> aj

I actually discussed the tiff situation on IRC before making the
changelog entries.  My exact concern was the one you raised: whether
the changlog entries should be in chronological order or in version
order.  3.7.0 was a complete repackaging of tiff.  The only reason
there were two simultaneous branches was because 3.7.0-2 introduced a
new binary package and was waiting in NEW when the two security
changes to 3.6.1 came out.  Otherwise, 3.7.1, which had already been
released, would have directly followed 3.6.1-3.  One reason for
putting the entries in version number order rather than in
chronological order was so that debuild -v3.6.1-5 would close all the
bugs tagged fixed-in-experimental from 3.7.0-1 and 3.7.0-2.  To be
honest, I didn't investigate whether the right thing would have
happened had I gone in chronological order.

> Travis Crump wrote:
>> Should changelogs be in chronological order or should they be in
>> version number order?
>
> The changelog should be in the order changes were made.
>
>> Specifically I just noticed that libtiff4's changelog is out of
>> chronological order[attached for reference].  It seems that the
>> maintainer was maintaining two branches: an experimental
>> branch[3.6.1-3->3.7.0-1->3.7.0-2], and an unstable/testing
>> branch[3.6.1-3->3.6.1-4->3.6.1-5].  3.7.1-1 would then be
>> potentially descended from either branch.
>
> If the changelog includes entries from 3.7.0-2 and 2.6.1-5, then
> 3.7.1-1
> should be descended from _both_ branches -- ie, it should include all
> the changes from both, merging any conflicts.

Since this was a complete repackaging, literally speaking, 3.7.0-1 did
not derive from 3.6.1-3 so there's no issue of merging changes, etc.
I can assure you, however, that 3.7.1-1 includes the security fixes
made in 3.6.1-4 and 3.6.1-5.  The former was already present in 3.7.1,
and the latter appears as an explicit patch in the 3.7.1 package.

Perhaps I should have mentioned explicitly in 3.7.1-1 that security
fixes had been applied, but I did not because they were already
mentioned in earlier changelog entries.  The fact that 3.7.0-1 came
right after 3.6.1-3 is a point that only a very observant person
looking carefully at the dates would really know about.  If I had made
explicit mention, someone might scratch their head and say, "Why is he
repeating mention of previously noted changes?"

I'm walking away from this discussion with the impression that I
handled the changlog for tiff correctly.  If I should walk away with a
different conclusion, someone should please point that out to me. :-)

-- 
Jay Berkenbilt <ejb@ql.org>
http://www.ql.org/q/