Reordering in package changelogs (was Re: rawhide report: 20100129 changes)

[Björn Persson]

Nicolas Mailhot wrote:
> Le Mar 2 février 2010 21:14, Björn Persson a écrit :
> > Nicolas Mailhot wrote:
> >> This changelog style conforms to the existing spec, it has been in use
> >> in Fedora for several years, it may surprise you, but changing the spec
> >> retroactively is not the way to prove your point.
> >
> > There's a spec? Where? I want to read it.
> 
> http://fedoraproject.org/wiki/Packaging/Guidelines#Changelogs

That's four examples of changelog entries. Examples are good but they're no 
replacement for a specification. It's not at all clear which details are 
mandatory syntax elements and which are merely the preferences of the person 
who wrote the examples.

After the line "You must use one of the following formats" there are three 
examples that each contain an email address with an @ in it. It may look like 
the @ has to be there, but in the example above that the @ has been replaced 
with " at ". If that's OK, then what other variations are OK? Is the USA-
centric date format mandatory for example, or are ISO 8601 dates permitted? 
Does it matter if the day number has a leading zero? Do the lines have to 
begin with asterisks and hyphens or can I use middle dots or en dashes 
instead? Do I have to refer to a bug report as "(#42)" or can I write "See bug 
42." instead? Does the address have to be an email address, or is a SIP 
address OK since it has the same format?

Note: I have an idea of the answers to these questions. My point is that the 
examples don't anwer them.

The question being discussed here seems to be how many changes should be 
grouped together in a single changelog entry. Should there be one entry for 
every CVS commit? One for each Koji build? One per day? One for every single 
atomic change made, with only one line-with-a-dash under each line-with-an-
asterisk? What if someone were to use a single gigantic changelog entry in 
their package, adding a new line-with-a-dash for every change but updating the 
date instead of adding new lines-with-asterisks? Where is it written that that 
would be wrong?

All of the examples contain one date, one name, one email address, one 
version-release number and one change description. Should I conclude that each 
entry must contain exactly one of each of those? If there may be multiple 
change descriptions in a single entry, and maybe multiple version-release 
numbers too, then what about multiple names or multiple dates?

Kevin's description here is closer to a specification of the syntax:
http://lists.fedoraproject.org/pipermail/devel/2009-April/027843.html
but even that doesn't address the question that you guys are arguing, which is 
more semantic in nature. This argument wouldn't have happened if a 
specification had existed.

Björn Persson
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 190 bytes
Desc: This is a digitally signed message part.
Url : http://lists.fedoraproject.org/pipermail/devel/attachments/20100205/76ab1280/attachment.bin