Mention optional special role for the first changelog line

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index 432e3221d7bfcc93758b83b927ed3dfc483b6720..83d42a9f38b15210852ace0932ec427480d4dc3f 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -1636,7 +1636,15 @@
          The maintainer name and email address used in the changelog
          should be the details of the person uploading <em>this</em>
          version.  They are <em>not</em> necessarily those of the
-         usual package maintainer.  The information here will be
+         usual package maintainer<footnote>
+           If the developer uploading the package is not one of the usual
+           maintainers of the package (as listed in the
+           <qref id="f-Maintainer"><tt>Maintainer</tt></qref> or
+           <qref id="f-Uploaders"><tt>Uploaders</tt></qref> control fields of
+           the package), the first line of the changelog is conventionally used
+           to explain why a non-maintainer is uploading the package.  The
+           Debian Developer's Reference (see <ref id="related">) documents the
+           conventions used.</footnote>.  The information here will be
          copied to the <tt>Changed-By</tt> field in the
          <tt>.changes</tt> file (see <ref id="f-Changed-By">),
          and then later used to send an acknowledgement when the
@@ -2218,16 +2226,16 @@ endif
        <heading>Variable substitutions: <file>debian/substvars</file></heading>
 
        <p>
-         When <prgn>dpkg-gencontrol</prgn>,
-         <prgn>dpkg-genchanges</prgn> and <prgn>dpkg-source</prgn>
-         generate control files, they perform variable substitutions
-         on their output just before writing it.  Variable
+         When <prgn>dpkg-gencontrol</prgn>
+         generates <qref id="binarycontrolfiles">binary package control
+         files</qref> (<file>DEBIAN/control</file>), it performs variable
+         substitutions on its output just before writing it.  Variable
          substitutions have the form <tt>${<var>variable</var>}</tt>.
          The optional file <file>debian/substvars</file> contains
          variable substitutions to be used; variables can also be set
          directly from <file>debian/rules</file> using the <tt>-V</tt>
-         option to the source packaging commands, and certain
-         predefined variables are also available.
+         option to the source packaging commands, and certain predefined
+         variables are also available.
        </p>
 
        <p>
@@ -5495,6 +5503,14 @@ Replaces: mail-transport-agent
        (<prgn>ld</prgn>) when compiling packages, as it will only look for
        <file>libgdbm.so</file> when compiling dynamically.
       </p>
+
+      <p>
+       If the package provides Ada Library Information
+       (<file>*.ali</file>) files for use with GNAT, these files must be
+       installed read-only (mode 0444) so that GNAT will not attempt to
+       recompile them.  This overrides the normal file mode requirements
+       given in <ref id="permissions-owners">.
+      </p>
       </sect>
 
       <sect id="sharedlibs-intradeps">
@@ -8014,11 +8030,13 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
        </p>
 
        <p>
-         Log files must be rotated occasionally so that they don't
-         grow indefinitely; the best way to do this is to drop a log
-         rotation configuration file into the directory
-         <file>/etc/logrotate.d</file> and use the facilities provided by
-         logrotate.<footnote>
+         Log files must be rotated occasionally so that they don't grow
+         indefinitely.  The best way to do this is to install a log
+         rotation configuration file in the
+         directory <file>/etc/logrotate.d</file>, normally
+         named <file>/etc/logrotate.d/<var>package</var></file>, and use
+         the facilities provided by <prgn>logrotate</prgn>.
+         <footnote>
            <p>
              The traditional approach to log files has been to set up
              <em>ad hoc</em> log rotation schemes using simple shell
@@ -8043,17 +8061,20 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
            section="8">):
          <example compact="compact">
 /var/log/foo/*.log {
-rotate 12
-weekly
-compress
-postrotate
-/etc/init.d/foo force-reload
-endscript
+    rotate 12
+    weekly
+    compress
+    missingok
+    postrotate
+        start-stop-daemon -K -p /var/run/foo.pid -s HUP -x /usr/sbin/foo -q
+    endscript
 }
          </example>
          This rotates all files under <file>/var/log/foo</file>, saves 12
-         compressed generations, and forces the daemon to reload its
-         configuration information after the log rotation.
+         compressed generations, and tells the daemon to reopen its log
+         files after the log rotation.  It skips this log rotation
+         (via <tt>missingok</tt>) if no such log file is present, which
+         avoids errors if the package is removed but not purged.
        </p>
 
        <p>
@@ -8065,7 +8086,7 @@ endscript
        </p>
       </sect>
 
-      <sect>
+      <sect id="permissions-owners">
        <heading>Permissions and owners</heading>
 
        <p>
@@ -8106,6 +8127,12 @@ endscript
           </footnote>
        </p>
 
+       <p>
+         Control information files should be owned by <tt>root:root</tt>
+         and either mode 644 (for most files) or mode 755 (for
+         executables such as <qref id="maintscripts">maintainer
+         scripts</qref>).
+       </p>
 
        <p>
          Setuid and setgid executables should be mode 4755 or 2755