6.3.5. Supplementing changelogs with NEWS.Debian files

Important news about changes in a package can also be put in NEWS.Debian files. The news will be displayed by tools like apt-listchanges, before all the rest of the changelogs. This is the preferred means to let the user know about significant changes in a package. It is better than using debconf notes since it is less annoying and the user can go back and refer to the NEWS.Debian file after the install. And it’s better than listing major changes in README.Debian, since the user can easily miss such notes.

The file format is the same as a debian changelog file, but leave off the asterisks and describe each news item with a full paragraph when necessary rather than the more concise summaries that would go in a changelog. It’s a good idea to run your file through dpkg-parsechangelog to check its formatting as it will not be automatically checked during build as the changelog is. Here is an example of a real NEWS.Debian file:

  1. cron (3.0pl1-74) unstable; urgency=low
  3.     The checksecurity script is no longer included with the cron package:
  4.     it now has its own package, checksecurity. If you liked the
  5.     functionality provided with that script, please install the new
  6.     package.
  8.  -- Steve Greenland <stevegr@debian.org>  Sat,  6 Sep 2003 17:15:03 -0500

The NEWS.Debian file is installed as /usr/share/doc/package/NEWS.Debian.gz. It is compressed, and always has that name even in Debian native packages. If you use debhelper, dh_installchangelogs will install debian/NEWS files for you.

Unlike changelog files, you need not update NEWS.Debian files with every release. Only update them if you have something particularly newsworthy that user should know about. If you have no news at all, there’s no need to ship a NEWS.Debian file in your package. No news is good news!