dpkg-maintscript-helper(1): update definition of "lastversion/priorversion"

Recommend usage of the version removing/renaming a conffile with a "~" suffix
as "priorversion" parameter. This ensures that a locally rebuilt package
will also trigger the operation on upgrade.

Reported-by: Sam Morris <sam@robots.org.uk>
Closes: #658854
Improved-by: Raphaël Hertzog <hertzog@debian.org>
Signed-off-by: Raphaël Hertzog <hertzog@debian.org>

debian/changelog

@@ -94,6 +94,10 @@ dpkg (1.16.2) UNRELEASED; urgency=low
     exist. Closes: #229357
   * Improve deb-shlibs(5) to mention that the dependency field must
     use the same syntax than a Depends field. Closes: #658696
+  * Update dpkg-maintscript-helper(1) to recommend usage of the version
+    removing/renaming a conffile with a "~" suffix as "priorversion"
+    parameter. Thanks to Sam Morris <sam@robots.org.uk> for the patch.
+    Closes: #658854
 
   [ Jonathan Nieder ]
   * Bump po4a version in Build-Depends to 0.41, since earlier versions do

man/dpkg-maintscript-helper.1

@@ -1,6 +1,6 @@
 .\" dpkg manual page - dpkg-maintscript-helper(1)
 .\"
-.\" Copyright © 2010 Raphaël Hertzog <hertzog@debian.org>
+.\" Copyright © 2010-2012 Raphaël Hertzog <hertzog@debian.org>
 .\"
 .\" This is free software; you can redistribute it and/or modify
 .\" it under the terms of the GNU General Public License as published by
@@ -15,7 +15,7 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .
-.TH dpkg\-maintscript\-helper 1 "2011-08-14" "Debian Project" "dpkg suite"
+.TH dpkg\-maintscript\-helper 1 "2012-02-08" "Debian Project" "dpkg suite"
 .SH NAME
 dpkg\-maintscript\-helper \- works around known dpkg limitations in maintainer scripts
 .
@@ -25,9 +25,9 @@ dpkg\-maintscript\-helper \- works around known dpkg limitations in maintainer s
 .
 .SH COMMANDS AND PARAMETERS
 .P
-\fBrm_conffile\fP \fIconffile\fP [\fIlastversion\fP [\fIpackage\fP]]
+\fBrm_conffile\fP \fIconffile\fP [\fIpriorversion\fP [\fIpackage\fP]]
 .P
-\fBmv_conffile\fP \fIoldconffile\fP \fInewconffile\fP [\fIlastversion\fP [\fIpackage\fP]]
+\fBmv_conffile\fP \fIoldconffile\fP \fInewconffile\fP [\fIpriorversion\fP [\fIpackage\fP]]
 .
 .SH DESCRIPTION
 .P
@@ -69,17 +69,30 @@ All of this is implemented by putting the following shell snippet in the
 \fBpreinst\fP, \fBpostinst\fP and \fBpostrm\fP maintainer scripts:
 .P
     dpkg\-maintscript\-helper rm_conffile \\
-        \fIconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@"
+        \fIconffile\fP \fIpriorversion\fP \fIpackage\fP \-\- "$@"
 .P
 \fIconffile\fP is the filename of the conffile to remove.
-\fIlastversion\fP is the last version of the package that contained the
-conffile (or the last version of the package that did not take care to
-remove the obsolete conffile if this was not immediately implemented).
-If \fIlastversion\fP is empty or omitted, then the operation is tried
-on every upgrade. \fIpackage\fP is the package name, it's optional as it will
-default to $DPKG_MAINTSCRIPT_PACKAGE (this variable is set by dpkg to the
-name of the package acted upon). All the parameters of the maintainer
-scripts have to be forwarded to the program after "\-\-".
+.P
+\fIpriorversion\fP defines the latest version of the package whose
+upgrade should trigger the removal. It is important to calculate
+\fIpriorversion\fP correctly so that conffiles are correctly removed even
+if the user rebuilt the package with a local version. For example, for a
+conffile removed in version \fB2.0\-1\fP of a package, \fIpriorversion\fP
+should be set to \fB2.0\-1~\fP. This will cause the conffile to be removed
+even if the user rebuilt the previous version \fB1.0\-1\fP as
+\fB1.0\-1local1\fP.
+.P
+If the conffile has not been shipped for several versions, and you are now
+modifying the maintainer scripts to clean up the obsolete file,
+\fIpriorversion\fP should be based on the version of the package that you are
+now preparing, not the first version of the package that lacked the
+conffile.
+.P
+\fIpackage\fP is the package name. If empty or omitted, the
+DPKG_MAINTSCRIPT_PACKAGE environment variable (as set by dpkg) will be used.
+.P
+All the parameters of the maintainer scripts have to be forwarded to the
+program after "\-\-".
 .P
 Current implementation: in the \fBpreinst\fP, it checks if the conffile
 was modified and renames it either to \fIconffile\fP\fB.dpkg\-remove\fP (if not
@@ -103,17 +116,22 @@ snippet in the \fBpreinst\fP, \fBpostinst\fP and \fBpostrm\fP maintainer
 scripts:
 .P
     dpkg\-maintscript\-helper mv_conffile \\
-        \fIoldconffile\fP \fInewconffile\fP \fIlastversion\fP \fIpackage\fP \-\- "$@"
+        \fIoldconffile\fP \fInewconffile\fP \fIpriorversion\fP \fIpackage\fP \-\- "$@"
 .P
 \fIoldconffile\fP and \fInewconffile\fP are the old and new name of the
-conffile to rename. \fIlastversion\fP is the last version of the package
-that contained the conffile with the old name. If \fIlastversion\fP is
+conffile to rename.
+.P
+\fIpriorversion\fP defines the latest version of the package whose upgrade
+should trigger the rename of the conffile (see the notes for
+\fBrm_conffile\fR above concerning the correct value). If \fIpriorversion\fP is
 empty or omitted, then the operation is tried on every upgrade (note: it's
-safer to give the version and have the operation tried only once). \fIpackage\fP
-is the package name, it's optional as it will default to
-$DPKG_MAINTSCRIPT_PACKAGE (this variable is set by dpkg to the name of the
-package acted upon). All the parameters of the maintainer scripts have to
-be forwarded to the program after "\-\-".
+safer to give the version and have the operation tried only once).
+.P
+\fIpackage\fP is the package name. If empty or omitted, the
+DPKG_MAINTSCRIPT_PACKAGE environment variable (as set by dpkg) will be used.
+.P
+All the parameters of the maintainer scripts have to be forwarded to the
+program after "\-\-".
 .P
 Current implementation: the \fBpreinst\fP checks if the conffile has been
 modified, if yes it's left on place otherwise it's renamed to