From: Russ Allbery <rra@debian.org>
Date: Sat, 5 Jul 2008 23:08:41 +0000 (-0700)
Subject: Clarify handling of diversions in maintainer scripts
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=1eb0a4f2fd24d928c4bc08419dd70e94c4b7a658;p=debian%2Fdebian-policy.git

Clarify handling of diversions in maintainer scripts

Suggest running dpkg-divert unconditionally in the preinst to also
catch cases of upgrading a package from a version before the diversion
was added.  Suggest an alternate form that doesn't re-add the diversion
when unnecessary on upgrades.

In the postrm example, remove the diversion in more cases and document
why it should not be removed on upgrades.

Closes: #483418
---

diff --git a/policy.sgml b/policy.sgml
index 24c9072..0cd241a 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -10564,26 +10564,37 @@ install-info --quiet --remove /usr/share/info/foobar.info
 	supposing that a <prgn>smailwrapper</prgn> package wishes to
 	install a wrapper around <file>/usr/sbin/smail</file>:
 	<example>
-  if [ install = "$1"  ]; then
-     dpkg-divert --package smailwrapper --add --rename \
-        --divert /usr/sbin/smail.real /usr/sbin/smail
-  fi
-	</example> Testing <tt>$1</tt> is necessary so that the script
-	doesn't try to add the diversion again when
-	<prgn>smailwrapper</prgn> is upgraded.  The <tt>--package
-	smailwrapper</tt> ensures that <prgn>smailwrapper</prgn>'s
-	copy of <file>/usr/sbin/smail</file> can bypass the diversion and
-	get installed as the true version.
+   dpkg-divert --package smailwrapper --add --rename \
+      --divert /usr/sbin/smail.real /usr/sbin/smail
+	</example> The <tt>--package smailwrapper</tt> ensures that
+	<prgn>smailwrapper</prgn>'s copy of <file>/usr/sbin/smail</file>
+	can bypass the diversion and get installed as the true version.
+	It's safe to add the diversion unconditionally on upgrades since
+	it will be left unchanged if it already exists, but
+	<prgn>dpkg-divert</prgn> will display a message.  To suppress that
+	message, make the command conditional on the version from which
+	the package is being upgraded:
+	<example>
+   if [ upgrade != "$1" ] || dpkg --compare-versions "$2" lt 1.0-2; then
+      dpkg-divert --package smailwrapper --add --rename \
+         --divert /usr/sbin/smail.real /usr/sbin/smail
+   fi
+	</example> where <tt>1.0-2</tt> is the version at which the
+	diversion was first added to the package.  Running the command
+	during abort-upgrade is pointless but harmless.
       </p>
 
       <p>
 	The postrm has to do the reverse:
 	<example>
-  if [ remove = "$1" ]; then
+  if [ remove = "$1" -o abort-install = "$1" -o disappear = "$1" ]; then
      dpkg-divert --package smailwrapper --remove --rename \
         --divert /usr/sbin/smail.real /usr/sbin/smail
   fi
-	</example>
+	</example> The postrm should not remove the diversion on upgrades
+	both because there's no reason to remove the diversion only to
+	immediately re-add it and since the postrm of the old package is
+	run after unpacking so the removal of the diversion will fail.
       </p>
 
       <p>