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

Bug#578854: New workding for Conflicts, Breaks, and related sections



Here's a fairly comprehensive reworking of the sections in Policy about
Breaks, Conflicts, and Replaces.  Please review, particularly from the
package manager side to be sure that what I'm describing will indeed work
correctly in the package management system.

diff --git a/policy.sgml b/policy.sgml
index 32eb5c2..7cac854 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -4641,17 +4641,29 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 	<p>
 	  Normally a <tt>Breaks</tt> entry will have an "earlier than"
 	  version clause; such a <tt>Breaks</tt> is introduced in the
-	  version of an (implicit or explicit) dependency which
-	  violates an assumption or reveals a bug in earlier versions
-	  of the broken package.  This use of <tt>Breaks</tt> will
-	  inform higher-level package management tools that broken
-	  package must be upgraded before the new one.
+	  version of an (implicit or explicit) dependency which violates
+	  an assumption or reveals a bug in earlier versions of the broken
+	  package, or which takes over a file from earlier versions of the
+	  broken package.  This use of <tt>Breaks</tt> will inform
+	  higher-level package management tools that broken package must
+	  be upgraded before the new one.
 	</p>
 
 	<p>
 	  If the breaking package also overwrites some files from the
-	  older package, it should use <tt>Replaces</tt> (not
-	  <tt>Conflicts</tt>) to ensure this goes smoothly.
+	  older package, it should use <tt>Replaces</tt> to ensure this
+	  goes smoothly.  See <ref id="replaces"> for a full discussion
+	  of taking over files from other packages, including how to
+	  use <tt>Breaks</tt> in those cases.
+	</p>
+
+	<p>
+	  Many of the cases where <tt>Breaks</tt> should be used were
+	  previously handled with <tt>Conflicts</tt>
+	  because <tt>Breaks</tt> did not yet exist.
+	  Many <tt>Conflicts</tt> fields should now be <tt>Breaks</tt>.
+	  See <ref id="conflicts"> for more information about the
+	  differences.
 	</p>
       </sect>
 
@@ -4662,21 +4674,24 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
           When one binary package declares a conflict with another
 	  using a <tt>Conflicts</tt> field, <prgn>dpkg</prgn> will
 	  refuse to allow them to be installed on the system at the
-	  same time.
+	  same time.  This is a stronger restriction than <tt>Breaks</tt>,
+	  which just prevents both packages from being configured at the
+	  same time.  Conflicting packages cannot be unpacked on the
+	  system at the same time.
 	</p>
 
 	<p>
 	  If one package is to be installed, the other must be removed
-	  first - if the package being installed is marked as
-	  replacing (see <ref id="replaces">) the one on the system,
-	  or the one on the system is marked as deselected, or both
-	  packages are marked <tt>Essential</tt>, then
-	  <prgn>dpkg</prgn> will automatically remove the package
-	  which is causing the conflict, otherwise it will halt the
-	  installation of the new package with an error.  This
-	  mechanism is specifically designed to produce an error when
-	  the installed package is <tt>Essential</tt>, but the new
-	  package is not.
+	  first.  If the package being installed is marked as replacing
+	  (see <ref id="replaces">, but note that <tt>Breaks</tt> should
+	  normally be used in this case) the one on the system, or the one
+	  on the system is marked as deselected, or both packages are
+	  marked <tt>Essential</tt>, then <prgn>dpkg</prgn> will
+	  automatically remove the package which is causing the conflict.
+	  Otherwise, it will halt the installation of the new package with
+	  an error.  This mechanism is specifically designed to produce an
+	  error when the installed package is <tt>Essential</tt>, but the
+	  new package is not.
 	</p>
 
 	<p>
@@ -4696,12 +4711,49 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
 	</p>
 
 	<p>
-	  A <tt>Conflicts</tt> entry should almost never have an
-	  "earlier than" version clause.  This would prevent
-	  <prgn>dpkg</prgn> from upgrading or installing the package
-	  which declared such a conflict until the upgrade or removal
-	  of the conflicted-with package had been completed.  Instead,
-	  <tt>Breaks</tt> may be used.
+	  Normally, <tt>Breaks</tt> should be used instead
+	  of <tt>Conflicts</tt> since <tt>Conflicts</tt> imposes a
+	  stronger restriction on the ordering of package installation or
+	  upgrade and can make it more difficult for the package manager
+	  to find a correct solution to an upgrade or installation
+	  problem.  <tt>Breaks</tt> should be used
+	  <list>
+	    <item>when moving a file from one package to another (see
+	      <ref id="replaces">),</item>
+	    <item>when splitting a package (a special case of the previous
+	      one), or</item>
+	    <item>when the breaking package exposes a bug in or interacts
+	      badly with particular versions of the broken
+	      package.</item>
+	  </list>
+	  <tt>Conflicts</tt> should be used
+	  <list>
+	    <item>when two packages provide the same file and will
+	      continue to do so (but be aware that this is often an error
+	      that should be fixed rather than using <tt>Conflicts</tt> --
+	      see, for example, <ref id="binaries">),</item>
+	    <item>in conjunction with <tt>Provides</tt> when only one
+	      package providing a given virtual facility may be installed
+	      at a time (see <ref id="virtual">),</item>
+	    <item>in other cases where one must prevent simultaneous
+	      installation of two packages for reasons that are ongoing
+	      (not fixed in a later version of one of the packages) or
+	      that must prevent both packages from being unpacked at the
+	      same time, not just configured.</item>
+	  </list>
+	</p>
+
+	<p>
+	  A <tt>Conflicts</tt> entry may have an "earlier than" version
+	  clause if the reason for the conflict is corrected in a later
+	  version of one of the packages.  However, normally the presence
+	  of an "earlier than" version clause is a sign
+	  that <tt>Breaks</tt> should have been used instead.  An "earlier
+	  than" version clause in <tt>Conflicts</tt>
+	  prevents <prgn>dpkg</prgn> from upgrading or installing the
+	  package which declares such a conflict until the upgrade or
+	  removal of the conflicted-with package has been completed, which
+	  is a strong restriction.
 	</p>
       </sect>
 
@@ -4748,35 +4800,46 @@ Provides: bar
 	</p>
 
 	<p>
-	  If a relationship field has a version number attached
-	  then only real packages will be considered to see whether
-	  the relationship is satisfied (or the prohibition violated,
-	  for a conflict or breakage) - it is assumed that a real
-	  package which provides the virtual package is not of the
-	  "right" version.  So, a <tt>Provides</tt> field may not
-	  contain version numbers, and the version number of the
-	  concrete package which provides a particular virtual package
-	  will not be looked at when considering a dependency on or
-	  conflict with the virtual package name.
+	  If a relationship field has a version number attached, only real
+	  packages will be considered to see whether the relationship is
+	  satisfied (or the prohibition violated, for a conflict or
+	  breakage).  In other words, if a version number is specified,
+	  this is a request to ignore all <tt>Provides</tt> for that
+	  package name and consider only real packages.  The package
+	  manager will assume that a package which package which provides
+	  that virtual package is not of the "right" version.
+	  A <tt>Provides</tt> field may not contain version numbers, and
+	  the version number of the concrete package which provides a
+	  particular virtual package will not be considered when
+	  considering a dependency on or conflict with the virtual package
+	  name.<footnote>
+	    It is possible that a future release of <prgn>dpkg</prgn> may
+	    add the ability to specify a version number for each virtual
+	    package it provides.  This feature is not yet present,
+	    however, and is expected to be used only infrequently.
+	  </footnote>
 	</p>
 
 	<p>
-	  It is likely that the ability will be added in a future
-	  release of <prgn>dpkg</prgn> to specify a version number for
-	  each virtual package it provides.  This feature is not yet
-	  present, however, and is expected to be used only
-	  infrequently.
+	  To specify which of a set of real packages should be the default
+	  to satisfy a particular dependency on a virtual package, list
+	  the real package as an alternative before the virtual one.
 	</p>
 
 	<p>
-	  If you want to specify which of a set of real packages
-	  should be the default to satisfy a particular dependency on
-	  a virtual package, you should list the real package as an
-	  alternative before the virtual one.
+	  If the virtual package represents a facility that can only be
+	  provided by one real package at a time, such as
+	  the <package>mail-transport-agent</package> virtual package that
+	  requires installation of a binary that would conflict with all
+	  other providers of that virtual package (see
+	  <ref id="mail-transport-agents">), all packages providing that
+	  virtual package should also declare a conflict with it
+	  using <tt>Conflicts</tt>.  This will ensure that at most one
+	  provider of that virtual package is unpacked or installed at a
+	  time.
 	</p>
       </sect>
 
-
       <sect id="replaces"><heading>Overwriting files and replacing
 	  packages - <tt>Replaces</tt></heading>
 
@@ -4790,31 +4853,51 @@ Provides: bar
 	<sect1><heading>Overwriting files in other packages</heading>
 
 	  <p>
-	    Firstly, as mentioned before, it is usually an error for a
-	    package to contain files which are on the system in
-	    another package.
-	  </p>
-
-	  <p>
-	    However, if the overwriting package declares that it
-	    <tt>Replaces</tt> the one containing the file being
-	    overwritten, then <prgn>dpkg</prgn> will replace the file
-	    from the old package with that from the new.  The file
-	    will no longer be listed as "owned" by the old package.
+	    It is usually an error for a package to contain files which
+	    are on the system in another package.  However, if the
+	    overwriting package declares that it <tt>Replaces</tt> the one
+	    containing the file being overwritten, then <prgn>dpkg</prgn>
+	    will replace the file from the old package with that from the
+	    new.  The file will no longer be listed as "owned" by the old
+	    package and will be taken over by the new package.
+	    Normally, <tt>Breaks</tt> should be used in conjunction
+	    with <tt>Replaces</tt>.<footnote>
+	      To see why <tt>Breaks</tt> is required in addition
+	      to <tt>Provides</tt>, consider the
+	      case of a file in the package <package>foo</package> being
+	      taken over by the package <package>foo-data</package>.
+	      <tt>Replaces</tt> will allow <package>foo-data</package> to
+	      be installed and take over that file.  However,
+	      without <tt>Breaks</tt>, nothing
+	      requires <package>foo</package> to be upgraded to a newer
+	      version that knows it does not include that file and instead
+	      depends on <package>foo-data</package>.  Nothing would
+	      prevent the new <package>foo-data</package> package from
+	      being installed and then removed, removing the file that it
+	      took over from <package>foo</package>.  After that
+	      operation, the package manager would think the system was in
+	      a consistent state, but the <package>foo</package> package
+	      would be missing one of its files.
+	    </footnote>
 	  </p>
 
 	  <p>
 	    For example, if a package <package>foo</package> is split
 	    into <package>foo</package> and <package>foo-data</package>
-	    starting at version 1.2-3, <package>foo-data</package> should
-	    have the field
+	    starting at version 1.2-3, <package>foo-data</package> would
+	    have the fields
 	    <example compact="compact">
 Replaces: foo (&lt;&lt; 1.2-3)
+Breaks: foo (&lt;&lt; 1.2-3)
+	    </example compact="compact">
+	    in its control file.  The new version of the
+	    package <package>foo</package> would normally have the field
+	    <example>
+Depends: foo-data (&gt;= 1.2-3)
 	    </example>
-	    in its control file.  The package <package>foo</package>
-	    doesn't need any special control fields in this example,
-	    although would generally depend on or
-	    recommend <package>foo-data</package>.
+	    (or possibly <tt>Recommends</tt> or even <tt>Suggests</tt> if
+	    the files moved into <package>foo-data</package> are not
+	    required for normal operation).
 	  </p>
 
 	  <p>
@@ -4829,40 +4912,35 @@ Replaces: foo (&lt;&lt; 1.2-3)
 	    special argument to allow the package to do any final
 	    cleanup required.  See <ref id="mscriptsinstact">.
 	    <footnote>
-	      <p>
-		Replaces is a one way relationship -- you have to              
-		install the replacing package after the replaced
-		package.
-	      </p>
+	      Replaces is a one way relationship.  You have to install
+	      the replacing package after the replaced package.
 	    </footnote>
 	  </p>
 
 	  <p>
 	    For this usage of <tt>Replaces</tt>, virtual packages (see
 	    <ref id="virtual">) are not considered when looking at a
-	    <tt>Replaces</tt> field - the packages declared as being
+	    <tt>Replaces</tt> field.  The packages declared as being
 	    replaced must be mentioned by their real names.
 	  </p>
 
 	  <p>
-	    Furthermore, this usage of <tt>Replaces</tt> only takes
-	    effect when both packages are at least partially on the
-	    system at once, so that it can only happen if they do not
-	    conflict or if the conflict has been overridden.
+	    This usage of <tt>Replaces</tt> only takes effect when both
+	    packages are at least partially on the system at once.  It is
+	    not relevant if the packages conflict unless the conflict has
+	    been overridden.
 	  </p>
-
 	</sect1>
 
 	<sect1><heading>Replacing whole packages, forcing their
 	    removal</heading>
 
 	  <p>
-	    Secondly, <tt>Replaces</tt> allows the packaging system to
+	    Second, <tt>Replaces</tt> allows the packaging system to
 	    resolve which package should be removed when there is a
-	    conflict - see <ref id="conflicts">.  This usage only
-	    takes effect when the two packages <em>do</em> conflict,
-	    so that the two usages of this field do not interfere with
-	    each other.
+	    conflict (see <ref id="conflicts">).  This usage only takes
+	    effect when the two packages <em>do</em> conflict, so that the
+	    two usages of this field do not interfere with each other.
 	  </p>
 
 	  <p>
@@ -4876,7 +4954,8 @@ Conflicts: mail-transport-agent
 Replaces: mail-transport-agent
 	    </example>
 	    ensuring that only one MTA can be installed at any one
-	    time.
+	    time.  See <ref id="virtual"> for more information about this
+	    example.
 	</sect1>
       </sect>
 
@@ -7056,7 +7135,7 @@ exec /usr/lib/foo/foo "$@"
     <chapt id="files">
       <heading>Files</heading>
 
-      <sect>
+      <sect id="binaries">
 	<heading>Binaries</heading>
 
 	<p>

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>



Reply to: