FWIW, the developer's reference has a section describing proper use of
NEWS.Debian files. I post it here in full because IMHO many developers
need to read this again. In particular, many NEWS.Debian files I have
seen are not properly formatted (many use changelog style bullets
and are unnecessarily terse) and do not speak to the correct audience
(users, not package developers).
6.3.4. 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:
cron (3.0pl1-74) unstable; urgency=low
The checksecurity script is no longer included with the cron package:
it now has its own package, "checksecurity". If you liked the
functionality provided with that script, please install the new
package.
-- 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!
--
see shy jo
Attachment:
signature.asc
Description: Digital signature