[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Package changelog should contain, well, a log of changes

Hi fellow Debian folks,

Please, when composing debian/changelog for package releases, take a 
moment to reflect on what you put into that file and how you phrase it.

It is a changelog, so should contain a list of changes.

This is not a list of changes:

python3-defaults (3.2.3-4) unstable; urgency=high

  * py3clean: really close #681389

Yes, we have nifty mechanisms in place to close bugs based on magic 
phrasing of changelog entries, but that's a bonus, not the main purpose 
of that file.

Yes, it is possible to look up that bugreport online to learn more, or 
sometimes (like this one) learn more from reading further back in the 
logfile.  But that's bad style.

Please write (brief but) explicitly what was changed in the packaging, 
and please make each changelog section self-contained.

Something like this would be much better (yes it repeats some phrasing 
from earlier changelog section to be self-contained):

python3-defaults (3.2.3-4) unstable; urgency=high

  * py3clean: accept --package *and* directory name at the same time
    (really this time). Closes: #681389.

Some use nifty tools to reuse titles from bugreports in changelog 
entries.  But often those titles describe what is the bug, not what will 
be the change.

Please proofread your changelog before releasing a packaging, and make 
sure all entries describe what was _changed_.

(no examples of ill-doing like that in today's changelog - great!)


 - Jonas

 * Jonas Smedegaard - idealist & Internet-arkitekt
 * Tlf.: +45 40843136  Website: http://dr.jones.dk/

 [x] quote me freely  [ ] ask before reusing  [ ] keep private

Attachment: signature.asc
Description: Digital signature

Reply to: