From af06a4f388b382cee3c2982bfa62b2d8ff2aa271 Mon Sep 17 00:00:00 2001
From: aph <aph@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sat, 7 Dec 2002 07:26:22 +0000
Subject: [PATCH] Sec "Best practices for maintainer scripts" added, special
 credit here to Charles Briscoe-Smith for work dating back to 1998; include a
 POSIX shell snippet showing how to check if a command is the PATH, closes:
 #150384

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1964 313b444b-1b9f-4f58-a734-7bb04f332e8d
---
 common.ent                | 13 ++++++++
 developers-reference.sgml | 70 +++++++++++++++++++++++++++++++++++----
 2 files changed, 76 insertions(+), 7 deletions(-)

diff --git a/common.ent b/common.ent
index 341e875..1380d83 100644
--- a/common.ent
+++ b/common.ent
@@ -240,3 +240,16 @@ pool/non-free/n/
 pool/non-free/n/netscape/
      ...
 </example>">
+
+<!entity example-pathfind '<example>pathfind() {
+    OLDIFS="$IFS"
+    IFS=:
+    for p in $PATH; do
+        if [ -x "$p/$*" ]; then
+            IFS="$OLDIFS"
+            return 0
+        fi
+    done
+    IFS="$OLDIFS"
+    return 1
+}</example>'>
diff --git a/developers-reference.sgml b/developers-reference.sgml
index 26d0bcb..62ae0f1 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.147 $">
+  <!entity cvs-rev "$Revision: 1.148 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -2050,7 +2050,7 @@ basis as co-maintainer or backup maintainer
 (see <ref id="collaborative-maint">).
 
 
-    <sect id="porting">Porting and Being Ported
+    <sect id="porting">Porting and being ported
       <p>
 Debian supports an ever-increasing number of architectures.  Even if
 you are not a porter, and you don't use any architecture but one, it
@@ -2338,8 +2338,8 @@ should subscribe themselves to the appropriate source package.</p>
       </sect>
 
     <sect id="archive-manip">
-      <heading>Moving, Removing, Renaming, Adopting, and Orphaning
-      Packages</heading>
+      <heading>Moving, removing, renaming, adopting, and orphaning
+      packages</heading>
       <p>
 Some archive manipulation operations are not automated in the Debian
 upload process.  These procedures should be manually followed by
@@ -2922,7 +2922,7 @@ from Debian developers.  Feel free to pick and choose whatever works
 best for you.
 
     <sect id="bpp-debian-rules">
-        <heading>Best Practices for <file>debian/rules</file></heading>
+        <heading>Best practices for <file>debian/rules</file></heading>
         <p>
 The following recommendations apply to the <file>debian/rules</file>
 file.  Since <file>debian/rules</file> controls the build process and
@@ -3027,6 +3027,62 @@ this using an hand-crafted <file>debian/rules</file> file.
         </sect1>
       </sect>
 
+    <sect id="bpp-debian-maint-scripts">
+        <heading>Best practices for maintainer scripts</heading>
+        <p>
+Maintainer scripts include the files <file>debian/postinst</file>,
+<file>debian/preinst</file>, <file>debian/prerm</file> and
+<file>debian/postrm</file>.  These scripts take care of any package
+installation or deinstallation setup which isn't handled merely by the
+creation or removal of files and directories.  The following
+instructions supplement the <url id="&url-debian-policy;" name="Debian
+Policy">.
+        <p>
+Maintainer scripts must be idempotent.  That means that you need to
+make sure nothing bad will happen if the script is called twice where
+it would usually be called once.
+        <p>
+Standard input and output may be redirected (e.g. into pipes) for
+logging purposes, so don't rely on them being a tty.
+        <p>
+All prompting or interactive configuration should be kept to a
+minimum.  When it is necessary, you should use the
+<package>debconf</package> package for the interface.  Remember that
+prompting in any case can only be in the <tt>configure</tt> stage of
+the <file>postinst</file> script.
+        <p>
+Keep the maintainer scripts as simple as possible.  We suggest you use
+pure POSIX shell scripts.  Remember, if you do need any bash features,
+the maintainer script must have a bash shbang line.  Posix shell or
+Bash are preferred to Perl, since they enable
+<package>debhelper</package> to easily add bits to the scripts.
+        <p>
+If you change your maintainer scripts, be sure to test package
+removal, double installation, and purging.  Be sure that a purged
+package is completely gone, that is, it must remove any files created,
+directly or indirectly, in any maintainer script.
+        <p>
+If you need to check for the existance of a command, you should use
+something like
+<example>if [ -x /usr/sbin/install-docs ]; then ...</example>
+
+If you don't wish to hardcode the path of the command in your
+maintainer script, the following POSIX-compliant shell function may
+help:
+
+&example-pathfind;
+
+You can use this function to search <tt>$PATH</tt> for a command name,
+passed as an argument.  It returns true (zero) if the command was
+found, and false if not.  This is really the most portable way, since
+<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not
+POSIX.  While <prgn>which</prgn> is an acceptable alternative, since
+it is from the required <package>debianutils</package> package, it's
+not on the root partition, although that is probably not something
+that will cause a problem.
+
+
+
 <!--
 	<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
 	<p>
@@ -3243,7 +3299,7 @@ members in choosing what they want to work on and in choosing
 the most critical thing to spend their time on.
 
     <sect id="submit-bug">
-        <heading>Bug Reporting</heading>
+        <heading>Bug reporting</heading>
         <p>
 We encourage you to file bugs as you find them in Debian packages.  In
 fact, Debian developers are often the first line testers.  Finding and
@@ -3305,7 +3361,7 @@ in order to catch up the backlog of bugs that you have (you can ask
 for help on &email-debian-qa; or &email-debian-devel;). At the same
 time, you can look for co-maintainers (see <ref id="collaborative-maint">).
 	
-	<sect1 id="qa-bsp">Bug Squashing Parties
+	<sect1 id="qa-bsp">Bug squashing parties
 	<p>
 From time to time the QA group organizes bug squashing parties to get rid of
 as many problems as possible. They are announced on &email-debian-devel-announce;
-- 
2.30.2