Update maintainer script dependency language

Based on review and feedback from Steve Langasek.

diff --git a/policy.sgml b/policy.sgml
index c5976e3a94d9005029ea9e75fe22ce8c5ed8c815..8a70ebf618054fe640c1bd78661d6d0ae51eb1af 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -1106,7 +1106,7 @@
        <p>
          Sometimes, unpacking one package requires that another package
          be first unpacked <em>and</em> configured.  In this case, the
        <p>
          Sometimes, unpacking one package requires that another package
          be first unpacked <em>and</em> configured.  In this case, the

-         dependent package must specify this dependency in
+         depending package must specify this dependency in

          the <tt>Pre-Depends</tt> control field.
        </p>
 
          the <tt>Pre-Depends</tt> control field.
        </p>
 


@@ -3835,11 +3835,11 @@ Checksums-Sha256:
              the <prgn>preinst</prgn> script cannot rely on any files
              included in its package.  Only essential packages and
              pre-dependencies (<tt>Pre-Depends</tt>) may be assumed to be
              the <prgn>preinst</prgn> script cannot rely on any files
              included in its package.  Only essential packages and
              pre-dependencies (<tt>Pre-Depends</tt>) may be assumed to be

-             available.  Pre-dependencies will be at least unpacked.
-             They may be only unpacked or "Half-Configured", not
-             completely configured, but only if a previous version of the
-             pre-dependency was completely configured and the
-             pre-dependency had not been removed since then.
+             available.  Pre-dependencies will have been configured at
+             least once, but at the time the <prgn>preinst</prgn> is
+             called they may only be in an unpacked or "Half-Configured"
+             state if a previous version of the pre-dependency was
+             completely configured and has not been removed since then.

            </item>
 
            <tag><var>old-preinst</var> <tt>abort-upgrade</tt>
            </item>
 
            <tag><var>old-preinst</var> <tt>abort-upgrade</tt>


@@ -3872,7 +3872,9 @@ Checksums-Sha256:
              The files contained in the package will be unpacked.  All
              package dependencies will at least be unpacked.  If there
              are no circular dependencies involved, all package
              The files contained in the package will be unpacked.  All
              package dependencies will at least be unpacked.  If there
              are no circular dependencies involved, all package

-             dependencies will be configured.
+             dependencies will be configured.  For behavior in the case
+             of circular dependencies, see the discussion
+             in <ref id="binarydeps">.

            </item>
 
            <tag><var>old-postinst</var> <tt>abort-upgrade</tt>
            </item>
 
            <tag><var>old-postinst</var> <tt>abort-upgrade</tt>


@@ -3899,6 +3901,13 @@ Checksums-Sha256:
                foo's <tt>postinst abort-remove</tt> would be called with
                bar only "Half-Installed".
              </footnote>
                foo's <tt>postinst abort-remove</tt> would be called with
                bar only "Half-Installed".
              </footnote>

+             The <prgn>postinst</prgn> should still attempt any actions
+             for which its dependencies are required, since they will
+             normally be available, but consider the correct error
+             handling approach if those actions fail.  Aborting
+             the <prgn>postinst</prgn> action if commands or facilities
+             from the package dependencies are not available is often the
+             best approach.

            </item>
          </taglist>
        </p>
            </item>
          </taglist>
        </p>


@@ -3954,8 +3963,22 @@ Checksums-Sha256:
              previously been deconfigured and only be unpacked, at which
              point subsequent package changes do not consider its
              dependencies.  Therefore, all <prgn>postrm</prgn> actions
              previously been deconfigured and only be unpacked, at which
              point subsequent package changes do not consider its
              dependencies.  Therefore, all <prgn>postrm</prgn> actions

-             may only rely on essential packages and cannot assume that
-             the package's dependencies are available.
+             may only rely on essential packages and must gracefully skip
+             any actions that require the package's dependencies if those
+             dependencies are unavailable.<footnote>
+               This is often done by checking whether the command or
+               facility the <prgn>postrm</prgn> intends to call is
+               available before calling it.  For example:
+<example>
+if [ "$1" = purge ] && [ -e /usr/share/debconf/confmodule ]; then
+        . /usr/share/debconf/confmodule
+        db_purge
+fi
+</example>
+               in <prgn>postrm</prgn> purges the <prgn>debconf</prgn>
+               configuration for the package
+               if <package>debconf</package> is installed.
+             </foonote>

            </item>
 
            <tag><var>new-postrm</var> <tt>failed-upgrade</tt>
            </item>
 
            <tag><var>new-postrm</var> <tt>failed-upgrade</tt>


@@ -4683,15 +4706,16 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
          broken at some point and the dependency requirements violated
          for at least one package.  Packages involved in circular
          dependencies may not be able to rely on their dependencies being
          broken at some point and the dependency requirements violated
          for at least one package.  Packages involved in circular
          dependencies may not be able to rely on their dependencies being

-         configured when being configured depending on which side of the
-         break of the circular dependency loop they happen to be on.  If
-         one of the packages in the loop has no <prgn>postinst</prgn>
-         script, then the cycle will be broken at that package; this
-         ensures that all <prgn>postinst</prgn> scripts are run with
-         their dependencies properly configured if this is possible.
-         Otherwise the breaking point is arbitrary.  Packages should
-         therefore avoid circular dependencies where possible,
-         particularly if they have <prgn>postinst</prgn> scripts.
+         configured before they themselves are configured, depending on
+         which side of the break of the circular dependency loop they
+         happen to be on.  If one of the packages in the loop has
+         no <prgn>postinst</prgn> script, then the cycle will be broken
+         at that package; this ensures that all <prgn>postinst</prgn>
+         scripts are run with their dependencies properly configured if
+         this is possible.  Otherwise the breaking point is arbitrary.
+         Packages should therefore avoid circular dependencies where
+         possible, particularly if they have <prgn>postinst</prgn>
+         scripts.

        </p>
 
        <p>
        </p>
 
        <p>


@@ -4718,15 +4742,23 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
                The <tt>Depends</tt> field should also be used if the
                <prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
                require the depended-on package to be unpacked or
                The <tt>Depends</tt> field should also be used if the
                <prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
                require the depended-on package to be unpacked or

-               configured in order to run.  In the case of <tt>postinst
-               configure</tt>, the depended-on packages will be unpacked
-               and configured first.  (If both packages are involved in a
-               dependency loop, this might not work as expected; see the
-               explanation a few paragraphs back.)  In the case
-               of <prgn>prerm</prgn> or other <prgn>postinst</prgn>
-               actions, the package dependencies will normally be at
-               least unpacked, but they may be only "Half-Installed" if a
-               previous upgrade of the dependency failed.
+               configured in order to run, or if the dependend-on package
+               is desirable for cleanup done by <prgn>postrm</prgn>.  In
+               the case of <tt>postinst configure</tt>, the depended-on
+               packages will be unpacked and configured first.  (If both
+               packages are involved in a dependency loop, this might not
+               work as expected; see the explanation a few paragraphs
+               back.)  In the case of <prgn>prerm</prgn> or
+               other <prgn>postinst</prgn> actions, the package
+               dependencies will normally be at least unpacked, but they
+               may be only "Half-Installed" if a previous upgrade of the
+               dependency failed.  In the case of <prgn>postrm</prgn>,
+               there are no guarantees, but the depended-on package is
+               more likely to be available if the package declares a
+               dependency (particularly for <tt>postrm remove</tt>).
+               The <prgn>postrm</prgn> script must cleanly skip actions
+               that require a dependency if that dependency isn't
+               available.

              </p>
            </item>
 
              </p>
            </item>