From 8fc1702045bdee7361e7171585c2dc7c44139765 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Fri, 20 Aug 2010 15:36:19 -0700
Subject: [PATCH] Document current behavior of conflicting conffiles

Document that the new package takes over the conffile from the removed
package when the packages conflict, and that the new package may see
left-over configuration files from the old package.  Reorder the section
to put the preferred solutions first.
---
 policy.sgml | 44 ++++++++++++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/policy.sgml b/policy.sgml
index 9037de8..bc25c16 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -7949,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
@@ -8014,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>
+	    A package that declares the same <tt>conffile</tt> as another,
+	    conflicting package may see left-over configuration files from
+	    that other package.  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>
-- 
2.39.2