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

Re: NEWS.Debian abuse

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

 -- 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

Reply to: