Clarify wording of conflicting packages with the same conffile

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

diff --git a/policy.sgml b/policy.sgml
index 06242900f3c728638a9708ebb3e2a016442ced1b..3fc844647317a43c5026842c7811f0523888baae 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -1826,23 +1826,26 @@
           identical behavior.
        </p>
 
+       <p>
+         The following targets are required and must be implemented
+         by <file>debian/rules</file>: <tt>clean</tt>, <tt>binary</tt>,
+         <tt>binary-arch</tt>, <tt>binary-indep</tt>, and <tt>build</tt>.
+         These are the targets called by <prgn>dpkg-buildpackage</prgn>.
+       </p>
+
        <p>
          Since an interactive <file>debian/rules</file> script makes it
-         impossible to auto-compile that package and also makes it
-         hard for other people to reproduce the same binary
-         package, all <em>required targets</em> must be
-         non-interactive. At a minimum, required targets are the
-         ones called by <prgn>dpkg-buildpackage</prgn>, namely,
-         <em>clean</em>, <em>binary</em>, <em>binary-arch</em>,
-         <em>binary-indep</em>, and <em>build</em>. It also follows
-         that any target that these targets depend on must also be
+         impossible to auto-compile that package and also makes it hard
+         for other people to reproduce the same binary package, all
+         required targets must be non-interactive.  It also follows that
+         any target that these targets depend on must also be
          non-interactive.
        </p>
 
        <p>
-         The targets are as follows (required unless stated otherwise):
+         The targets are as follows:
          <taglist>
-           <tag><tt>build</tt></tag>
+           <tag><tt>build</tt> (required)</tag>
            <item>
              <p>
                The <tt>build</tt> target should perform all the
@@ -1953,8 +1956,8 @@
              </p>
            </item>
 
-           <tag><tt>binary</tt>, <tt>binary-arch</tt>,
-             <tt>binary-indep</tt>
+           <tag><tt>binary</tt> (required), <tt>binary-arch</tt>
+             (required), <tt>binary-indep</tt> (required)
            </tag>
            <item>
              <p>
@@ -2002,7 +2005,7 @@
              </p>
            </item>
 
-           <tag><tt>clean</tt></tag>
+           <tag><tt>clean</tt> (required)</tag>
            <item>
              <p>
                This must undo any effects that the <tt>build</tt>
@@ -7946,22 +7949,6 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
        <sect1>
          <heading>Sharing configuration files</heading>
 
-         <p>
-           Packages which specify the same file as a
-           <tt>conffile</tt> must be tagged as <em>conflicting</em>
-           with each other.  (This is an instance of the general rule
-           about not sharing files.  Note that neither alternatives
-           nor diversions are likely to be appropriate in this case;
-           in particular, <prgn>dpkg</prgn> does not handle diverted
-           <tt>conffile</tt>s well.)
-         </p>
-
-         <p>
-           The maintainer scripts must not alter a <tt>conffile</tt>
-           of <em>any</em> package, including the one the scripts
-           belong to.
-         </p>
-
          <p>
            If two or more packages use the same configuration file
            and it is reasonable for both to be installed at the same
@@ -8011,6 +7998,34 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
            and which manages the shared configuration files.  (The
            <tt>sgml-base</tt> package is a good example.)
          </p>
+
+         <p>
+           If the configuration file cannot be shared as described above,
+           the packages must be marked as conflicting with each other.
+           Two packages that specify the same file as
+           a <tt>conffile</tt> must conflict.  This is an instance of the
+           general rule about not sharing files.  Neither alternatives
+           nor diversions are likely to be appropriate in this case; in
+           particular, <prgn>dpkg</prgn> does not handle diverted
+           <tt>conffile</tt>s well.
+         </p>
+
+         <p>
+           When two packages both declare the same <tt>conffile</tt>, they
+           may see left-over configuration files from each other even
+           though they conflict with each other.  If a user removes
+           (without purging) one of the packages and installs the other,
+           the new package will take over the <tt>conffile</tt> from the
+           old package.  If the file was modified by the user, it will be
+           treated the same as any other locally
+           modified <tt>conffile</tt> during an upgrade.
+         </p>
+
+         <p>
+           The maintainer scripts must not alter a <tt>conffile</tt>
+           of <em>any</em> package, including the one the scripts
+           belong to.
+         </p>
        </sect1>
 
        <sect1>