Record debhelper (13.11.5) in archive suite sid

4 files changed, 714 insertions, 330 deletions

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
deleted file mode 100644
index e7b6e355..00000000
--- a/doc/PROGRAMMING
+++ /dev/null
@@ -1,318 +0,0 @@
-This file documents things you should know to write a new debhelper program.
-Any program with a name that begins with dh_ should conform to these
-guidelines (with the historical exception of dh_make).
-
-Standardization:
----------------
-
-There are lots of debhelper commands. To make the learning curve shallower,
-I want them all to behave in a standard manner:
-
-All debhelper programs have names beginning with "dh_". This is so we don't
-pollute the name space too much.
-
-Debhelper programs should never output anything to standard output except
-error messages, important warnings, and the actual commands they run that
-modify files under debian/ (this last only if they are passed -v, and if you
-output the commands, you should indent them with 1 tab). This is so we don't
-have a lot of noise output when all the debhelper commands in a debian/rules
-are run, so the important stuff is clearly visible.
-
-Debhelper programs should accept all options listed in the "SHARED
-DEBHELPER OPTIONS" section of debhelper(7), including any long forms of
-these options, like --verbose . If necessary, the options may be ignored.
-
-If debhelper commands need config files, they should use
-debian/package.filename as the name of the config file (replace filename
-with whatever your command wants), and debian/filename should also be
-checked for config information for the first binary package in
-debian/control. Also, debhelper commands should accept the same sort of
-information that appears in the config files, on their command lines, if
-possible, and apply that information to the first package they act on.
-The config file format should be as simple as possible, generally just a
-list of files to act on.
-
-Debhelper programs should never modify the debian/postinst, debian/prerm,
-etc scripts. Instead, they can add lines to debian/postinst.debhelper, etc. 
-The autoscript() function (see below) is one easy way to do this.
-dh_installdeb is an exception, it will run after the other commands and
-merge these modifications into the actual postinst scripts.
-
-In general, files named debian/*.debhelper are internal to debhelper, and
-their existence or use should not be relied on by external programs such as
-the build process of a package. These files will be deleted by dh_clean.
-
-Debhelper programs should default to doing exactly what policy says to do.
-
-There are always exceptions. Just ask me.
-
-Introducing Dh_Lib:
-------------------
-
-Dh_Lib is the library used by all debhelper programs to parse their
-arguments and set some useful variables. It's not mandatory that your
-program use Dh_Lib.pm, but it will make it a lot easier to keep it in sync
-with the rest of debhelper if it does, so this is highly encouraged.
-
-Use Dh_Lib like this:
-
-use Debian::Debhelper::Dh_Lib
-init();
-
-The init() function causes Dh_lib to parse the command line and do some other
-initialization tasks.
-
-Argument processing:
--------------------
-
-All debhelper programs should respond to certain arguments, such as -v, -i,
--a, and -p. To help you make this work right, Dh_Lib.pm handles argument
-processing. Just call init().
-
-You can add support for additional options to your command by passing an
-options hash to init(). The hash is then passed on the Getopt::Long to
-parse the command line options. For example, to add a --foo option, which
-sets $dh{FOO}:
-
-init(options => { foo => \$dh{FOO} });
-
-After argument processing, some global variables are used to hold the
-results; programs can use them later. These variables are elements of the
-%dh hash.
-
-switch		variable	description
--v		VERBOSE		should the program verbosely output what it is
-				doing?
---no-act	NO_ACT		should the program not actually do anything?
--i,-a,-p,-N	DOPACKAGES	a space delimited list of the binary packages
-				to act on (in Dh_Lib.pm, this is an array)
--i		DOINDEP		set if we're acting on binary independent
-				packages
--a		DOARCH		set if we're acting on binary dependent
-				packages
--n		NOSCRIPTS	if set, do not make any modifications to the 
-				package's postinst, postrm, etc scripts.
--o		ONLYSCRIPTS	if set, only make modifications to the
-				package's scripts, but don't look for or
-				install associated files.
--X		EXCLUDE		exclude a something from processing (you
-				decide what this means for your program)
-				(This is an array)
--X              EXCLUDE_FIND	same as EXCLUDE, except all items are put
-				into a string in a way that they will make
-				find find them. (Use ! in front to negate
-				that, of course) Note that this should
-				only be used inside complex_doit(), not in
-				doit().
--d		D_FLAG		you decide what this means to your program
--k		K_FLAG		used to turn on keeping of something
--P		TMPDIR		package build directory (implies only one
-				package is being acted on)
--u		U_PARAMS	will be set to a string, that is typically
-				parameters your program passes on to some
-				other program. (This is an array)
--V		V_FLAG		will be set to a string, you decide what it
-				means to your program
--V		V_FLAG_SET	will be 1 if -V was specified, even if no
-				parameters were passed along with the -V
--A		PARAMS_ALL	generally means that additional command line
-				parameters passed to the program (other than
-				those processed here), will apply to all 
-				binary packages the program acts on, not just
-				the first
---priority	PRIORITY	will be set to a number
---mainpackage	MAINPACKAGE	controls which package is treated as the
-				main package to act on
---name		NAME		a name to use for installed files, instead of
-				the package name
---error-handler	ERROR_HANDLER	a function to call on error
-
-Any additional command line parameters that do not start with "-" will be 
-ignored, and you can access them later just as you normally would.
-
-Global variables:
-----------------
-
-The following keys are also set in the %dh hash when you call init():
-
-MAINPACKAGE	the name of the first binary package listed in
-		debian/control
-FIRSTPACKAGE	the first package we were instructed to act on. This package
-		typically gets special treatment; additional arguments
-		specified on the command line may effect it.
-
-Functions:
----------
-
-Dh_Lib.pm also contains a number of functions you may find useful.
-
-doit(@command)
-	Pass this function an array that is a 
-	shell command. It will run the command (unless $dh{NO_ACT} is set), and
-	if $dh{VERBOSE} is set, it will also output the command to stdout. You
-	should use this function for almost all commands your program performs
-	that manipulate files in the package build directories.
-complex_doit($command)
-	Pass this function a string that is a shell command, it will run it
-	similarly to how doit() does. You can pass more complicated commands 
-	to this (ie, commands involving piping redirection), however, you 
-	have to worry about things like escaping shell metacharacters.
-verbose_print($message)
-	Pass this command a string, and it will echo it if $dh{VERBOSE} is set.
-error($errormsg)
-	Pass this command a string, it will output it to standard error and
-	exit.
-warning($message)
-	Pass this command a string, and it will output it to standard error
-	as a warning message.
-tmpdir($dir)
-	Pass this command the name of a binary package, it will return the
-	name of the tmp directory that will be used as this package's
-	package build directory. Typically, this will be "debian/package".
-compat($num)
-	Pass this command a number, and if the current compatibility level
-	is less than or equal to that number, it will return true.
-	Looks at DH_COMPAT to get the compatibility level.
-pkgfile($package, $basename)
-	Pass this command the name of a binary package, and the base name of a
-	file, and it will return the actual filename to use. This is used
-	for allowing debhelper programs to have configuration files in the
-	debian/ directory, so there can be one config file per binary
-	package. The convention is that the files are named
-	debian/package.filename, and debian/filename is also allowable for
-	the $dh{MAINPACKAGE}. If the file does not exist, nothing is returned.
-
-	If the *entire* behavior of a command, when run without any special
-	options, is determined by the existence of 1 or more pkgfiles,
-	or by the existence of a file or directory in a location in the
-	tmpdir, it can be marked as such, which allows dh to automatically
-	skip running it. This is done by inserting a special comment,
-	of the form:
-
-	# PROMISE: DH NOOP WITHOUT pkgfilea pkgfileb tmp(need/this)
-
-pkgext($package)
-	Pass this command the name of a binary package, and it will return
-	the name to prefix to files in debian/ for this package. For the
-	$dh{MAINPACKAGE}, it returns nothing (there is no prefix), for the other
-	packages, it returns "package.".
-isnative($package)
-	Pass this command the name of a package, it returns 1 if the package
-	is a native debian package.
-	As a side effect, $dh{VERSION} is set to the version number of the
-	package.
-autoscript($package, $scriptname, $snippetname, $sedcommands || $sub)
-	Pass parameters:
-	 - binary package to be affected
-	 - script to add to
-	 - filename of snippet
-	 - (optional) EITHER sed commands to run on the snippet. Ie,
-	   s/#PACKAGE#/$PACKAGE/ Note: Passed to the shell inside double
-           quotes.
-	   OR a perl sub to invoke with $_ set to each line of the snippet in
-           turn.
-	This command automatically adds shell script snippets to a debian
-	maintainer script (like the postinst or prerm).
-	Note that in v6 mode and up, the snippets are added in reverse
-	order for the removal scripts.
-dirname($pathname)
-	Return directory part of pathname.
-basename($pathname)
-	Return base of pathname,
-addsubstvar($package, $substvar, $deppackage, $verinfo, $remove)
-	This function adds a dependency on some package to the specified
-	substvar in a package's substvar's file. It needs all these
-	parameters:
-	- binary package that gets the item
-	- name of the substvar to add the item to
-	- the package that will be depended on
-	- version info for the package (optional) (ie: ">= 1.1")
-	- if this last parameter is passed, the thing that would be added
-	  is removed instead. This can be useful to ensure that a debhelper
-	  command is idempotent. (However, we generally don't bother,
-	  and rely on the user calling dh_prep.) Note that without this
-	  parameter, if you call the function twice with the same values it
-	  will only add one item to the substvars file.
-delsubstvar($package, $substvar)
-	This function removes the entire line for the substvar from the
-	package's shlibs file.
-excludefile($filename)
-	This function returns true if -X has been used to ask for the file
-	to be excluded.
-is_udeb($package)
-	Returns true if the package is marked as a udeb in the control
-	file.
-udeb_filename($package)
-	Returns the filename of the udeb package.
-getpackages($type)
-	Returns a list of packages in the control file.
-	Pass "arch" or "indep" to specify arch-dependent or
-	-independent. If nothing is specified, returns all
-	packages (including packages that are not built
-	for this architecture). Pass "both" to get the union
-	of "arch" and "indep" packages.
-	As a side effect, populates %package_arches and %package_types with
-	the types of all packages (not only those returned).
-inhibit_log()
-	Prevent logging the program's successful finish to
-	debian/*debhelper.log
-load_log($package, $hashref)
-	Loads the log file for the given package and returns a list of
-	logged commands.
-	(Passing a hashref also causes it to populate the hash.)
-write_log($cmd, $package ...)
-	Writes the log files for the specified package(s), adding
-	the cmd to the end.
-
-Sequence Addons:
----------------
-
-The dh(1) command has a --with <addon> parameter that ca be used to load
-a sequence addon module named Debian::Debhelper::Sequence::<addon>. 
-These modules can add/remove commands to the dh command sequences, by
-calling some functions from Dh_Lib:
-
-insert_before($existing_command, $new_command)
-	Insert $new_command in sequences before $existing_command
-
-insert_after($existing_command, $new_command)
-	Insert $new_command in sequences after $existing_command
-
-remove_command($existing_command)
-	Remove $existing_command from the list of commands to run
-	in all sequences.
-
-add_command($new_command, $sequence)
-	Add $new_command to the beginning of the specified sequence.
-	If the sequence does not exist, it will be created.
-
-add_command_options($command, $opt1, $opt2, ...)
-	Append $opt1, $opt2 etc. to the list of additional options which
-	dh passes when running the specified $command. These options are
-	not relayed to debhelper commands called via $command override.
-
-remove_command_options($command)
-	Clear all additional $command options previously added with
-	add_command_options().
-
-remove_command_options($command, $opt1, $opt2, ...)
-	Remove $opt1, $opt2 etc. from the list of additional options which
-	dh passes when running the specified $command.
-
-Buildsystem Classes:
--------------------
-
-The dh_auto_* commands are frontends that use debhelper buildsystem
-classes. These classes have names like Debian::Debhelper::Buildsystem::foo,
-and are derived from Debian::Debhelper::Buildsystem, or other, related
-classes.
-
-A buildsystem class needs to inherit or define these methods: DESCRIPTION,
-check_auto_buildable, configure, build, test, install, clean. See the comments
-inside Debian::Debhelper::Buildsystem for details. Note that this interface
-is still subject to change.
-
-Note that third-party buildsystems will not automatically be used by default,
-but can be forced to be used via the --buildsystem parameter.
-
--- Joey Hess <joeyh@debian.org>
diff --git a/doc/PROGRAMMING.md b/doc/PROGRAMMING.md
new file mode 100644
index 00000000..fd28b6a8
--- /dev/null
+++ b/doc/PROGRAMMING.md
@@ -0,0 +1,694 @@
+# PROGRAMMING
+
+This file documents things you should know to write a new debhelper program.
+Any program with a name that begins with `dh_` should conform to these
+guidelines (with the historical exception of `dh_make`).
+
+## Standardization
+
+There are lots of debhelper commands. To make the learning curve shallower,
+I want them all to behave in a standard manner:
+
+All debhelper programs have names beginning with `dh_`. This is so we don't
+pollute the name space too much.
+
+Debhelper programs should never output anything to standard output except
+error messages, important warnings, and the actual commands they run that
+modify files under `debian/` (this last only if they are passed `-v`, and if you
+output the commands, you should indent them with 1 tab). This is so we don't
+have a lot of noise output when all the debhelper commands in a `debian/rules`
+are run, so the important stuff is clearly visible.
+
+An exception to above rule are `dh_auto_*` commands and `dh` itself. They will
+also print the commands interacting with the upstream build system and which
+of the simple debhelper programs are called. (i.e. print what a traditional
+non-[dh(1)] using `debian/rules` would print but nothing else).
+
+Debhelper programs should accept all options listed in the "SHARED
+DEBHELPER OPTIONS" section of [debhelper(7)], including any long forms of
+these options, like `--verbose`. If necessary, the options may be ignored.
+
+If debhelper commands need config files, they should use
+`debian/package.filename` as the name of the config file (replace filename
+with whatever your command wants), and `debian/filename` should also be
+checked for config information for the first binary package in
+`debian/control`. Also, debhelper commands should accept the same sort of
+information that appears in the config files, on their command lines, if
+possible, and apply that information to the first package they act on.
+The config file format should be as simple as possible, generally just a
+list of files to act on.
+
+Debhelper programs should never modify the `debian/postinst`, `debian/prerm`,
+etc scripts. Instead, they can add lines to `debian/postinst.debhelper`, etc.
+The `autoscript()` function (see below) is one easy way to do this.
+`dh_installdeb` is an exception, it will run after the other commands and
+merge these modifications into the actual postinst scripts.
+
+In general, files named `debian/*.debhelper` and all content in
+`debian/.debhelper` are internal to debhelper, and their existence or
+use should not be relied on by external programs such as the build
+process of a package. These files will be deleted by `dh_clean`.
+
+Debhelper programs should default to doing exactly what policy says to do.
+
+There are always exceptions. Just ask me.
+
+## Introducing Dh_Lib
+
+`Dh_Lib` is the library used by all debhelper programs to parse their
+arguments and set some useful variables. It's not mandatory that your
+program use `Dh_Lib.pm`, but it will make it a lot easier to keep it in sync
+with the rest of debhelper if it does, so this is highly encouraged.
+
+Use `Dh_Lib` like this:
+
+    use Debian::Debhelper::Dh_Lib;
+    our $VERSION = '1.0';
+    init();
+
+The `init()` function causes `Dh_lib` to parse the command line and do
+some other initialization tasks.  If present, `$main::VERSION` will be
+used to determine the version of the tool (e.g. embedded into
+autoscript snippets).
+
+## Argument processing
+
+All debhelper programs should respond to certain arguments, such as `-v`, `-i`,
+`-a`, and `-p`. To help you make this work right, `Dh_Lib.pm` handles argument
+processing. Just call `init()`.
+
+You can add support for additional options to your command by passing an
+options hash to `init()`. The hash is then passed on the `Getopt::Long` to
+parse the command line options. For example, to add a `--foo` option, which
+sets `$dh{FOO}`:
+
+    init(options => { foo => \$dh{FOO} });
+
+After argument processing, some global variables are used to hold the
+results; programs can use them later. These variables are elements of the
+`%dh` hash.
+
+| switch              | variable        | description                                                                                                                                                                                                                      |
+|---------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `-v`                | `VERBOSE`       | should the program verbosely output what it is doing?                                                                                                                                                                            |
+| `--no-act`          | `NO_ACT`        | should the program not actually do anything?                                                                                                                                                                                     |
+| `-i`,`-a`,`-p`,`-N` | `DOPACKAGES`    | a space delimited list of the binary packages to act on (in `Dh_Lib.pm`, this is an array)                                                                                                                                       |
+| `-i`                | `DOINDEP`       | set if we're acting on binary independent packages                                                                                                                                                                               |
+| `-a`                | `DOARCH`        | set if we're acting on binary dependent packages                                                                                                                                                                                 |
+| `-n`                | `NOSCRIPTS`     | if set, do not make any modifications to the package's postinst, postrm, etc scripts.                                                                                                                                            |
+| `-o`                | `ONLYSCRIPTS`   | if set, only make modifications to the package's scripts, but don't look for or install associated files.                                                                                                                        |
+| `-X`                | `EXCLUDE`       | exclude something from processing (you decide what this means for your program) (This is an array)                                                                                                                               |
+| `-X`                | `EXCLUDE_FIND`  | same as `EXCLUDE`, except all items are put into a string in a way that they will make find find them. (Use `!` in front to negate that, of course) Note that this should only be used inside `complex_doit()`, not in `doit()`. |
+| `-d`                | `D_FLAG`        | you decide what this means to your program                                                                                                                                                                                       |
+| `-P`                | `TMPDIR`        | package build directory (implies only one package is being acted on)                                                                                                                                                             |
+| `-u`                | `U_PARAMS`      | will be set to a string, that is typically parameters your program passes on to some other program. (This is an array)                                                                                                           |
+| `-V`                | `V_FLAG`        | will be set to a string, you decide what it means to your program                                                                                                                                                                |
+| `-V`                | `V_FLAG_SET`    | will be 1 if `-V` was specified, even if no parameters were passed along with the `-V`                                                                                                                                           |
+| `-A`                | `PARAMS_ALL`    | generally means that additional command line parameters passed to the program (other than those processed here), will apply to all binary packages the program acts on, not just the first                                       |
+| `--mainpackage`     | `MAINPACKAGE`   | controls which package is treated as the main package to act on                                                                                                                                                                  |
+| `--name`            | `NAME`          | a name to use for installed files, instead of the package name                                                                                                                                                                   |
+| `--error-handler`   | `ERROR_HANDLER` | a function to call on error                                                                                                                                                                                                      |
+
+Any additional command line parameters that do not start with "`-`" will be
+ignored, and you can access them later just as you normally would.
+
+## Global variables
+
+The following keys are also set in the `%dh` hash when you call `init()`:
+
+- `MAINPACKAGE`
+
+  the name of the first binary package listed in `debian/control`
+
+- `FIRSTPACKAGE`
+
+  the first package we were instructed to act on. This package
+  typically gets special treatment; additional arguments
+  specified on the command line may effect it.
+
+## Functions
+
+`Dh_Lib.pm` also contains a number of functions you may find useful.
+
+- `doit([$options, ]@command)`
+
+  Pass this function an array that is a command with arguments.
+  It will run the command (unless `$dh{NO_ACT}` is set), and
+  if `$dh{VERBOSE}` is set, it will also output the command to stdout. You
+  should use this function for almost all commands your program performs
+  that manipulate files in the package build directories.
+
+  The `$options` argument (if passed) must be a hashref (added in debhelper 10.7).
+  The following key-value pairs can be used:
+
+  - `stdout` => A file name.  The child process will have its STDOUT redirected
+    to that file.  [debhelper (>= 10.7)]
+  - `chdir` => A directory.  The child process will do a chdir into that
+    directory before executing the command.  [debhelper (>= 10.9)]
+  - `update_env` => A hashref.  Each key in it represents an environment variable
+    that should be set in the child (possibly replacing the existing value)
+    prior to the exec.  If the value is undef, the environment variable will
+    be unset.  Environment variables in `%ENV` but not listed in the `update_env`
+    hashref will be preserved as-is.  [debhelper (>= 11.1)]
+
+  This will *not* invoke a shell, so meta characters will not have any special
+  meaning.  Use `complex_doit` for that (or emulate via `bash -c`).  
+  NB: In compat 11 and below, there was a bug that would make `doit` fork a shell
+  in one special case.  This is deprecated and will be removed in compat 12.
+  The detection code for this can be disabled by passing an empty hashref for
+  as `$options`.  This will make doit unconditionally avoid forking a shell.
+
+- `print_and_doit([$options, ]@command)`
+
+  Like `doit` but will print unless `$dh{QUIET}` is set. See "Standardization"
+  above for when this is allowed to be called.
+
+- `complex_doit($command)`
+
+  Pass this function a string that is a shell command, it will run it
+  similarly to how `doit()` does. You can pass more complicated commands
+  to this (i.e. commands involving piping redirection), however, you
+  have to worry about things like escaping shell metacharacters.
+
+- `verbose_print($message)`
+
+  Pass this command a string, and it will echo it if `$dh{VERBOSE}` is set.
+
+- `nonquiet_print($message)`
+
+  Pass this command a string, and it will echo it unless `$dh{QUIET}` is set.
+  See "Standardization" above for when this is allowed to be called.
+
+- `error($errormsg)`
+
+  Pass this command a string, it will output it to standard error and
+  exit.
+
+- `error_exitcode($cmd)`
+
+  Pass this subroutine a string (representing a command line), it will
+  output a message describing that the command failed to standard error
+  and exit.  Note that this relies on the value of `$?` to produce a
+  meaningful error message.  Even if `$?` is `0`, this *will* still terminate
+  the program (although with a rather unhelpful message).
+
+- `warning($message)`
+
+  Pass this command a string, and it will output it to standard error
+  as a warning message.
+
+- `tmpdir($dir)`
+
+  Pass this command the name of a binary package, it will return the
+  name of the tmp directory that will be used as this package's
+  package build directory. Typically, this will be `debian/package`.
+
+- `compat($num)`
+
+  Pass this command a number, and if the current compatibility level
+  is less than or equal to that number, it will return true.
+  Looks at `DH_COMPAT` to get the compatibility level.
+
+- `pkgfile($package, $basename)`
+
+  Pass this command the name of a binary package, and the base name of a
+  file, and it will return the actual filename to use. This is used
+  for allowing debhelper programs to have configuration files in the
+  `debian/` directory, so there can be one config file per binary
+  package. The convention is that the files are named
+  `debian/package.filename`, and `debian/filename` is also allowable for
+  the `$dh{MAINPACKAGE}`. If the file does not exist, nothing is returned.
+
+  If the *entire* behavior of a command, when run without any special
+  options, is determined by the existence of 1 or more pkgfiles,
+  or by the existence of a file or directory in a location in the
+  tmpdir, it can be marked as such, which allows dh to automatically
+  skip running it.  Please see "Optimization techniques" below.
+
+- `pkgext($package)`
+
+  Pass this command the name of a binary package, and it will return
+  the name to prefix to files in `debian/` for this package. For the
+  `$dh{MAINPACKAGE}`, it returns nothing (there is no prefix), for the other
+  packages, it returns `package.`.
+
+- `isnative($package)`
+
+  Pass this command the name of a package, it returns 1 if the package
+  is a native debian package.
+  As a side effect, `$dh{VERSION}` is set to the version number of the
+  package.
+
+- `autoscript($package, $scriptname, $snippetname, $substparam)`
+
+  Pass parameters:
+  - binary package to be affected
+  - script to add to
+  - filename of snippet. For testing purposes, you can set the
+    environment variable `DH_DATAFILES` containing a autoscripts
+    directory, which can be used to shadow the snippets provided
+    in `/usr/share/debhelper/autoscripts` (or to test newly added
+    snippets).  
+    Older versions of debhelper (<< 13.1~) do not support
+    `DH_DATAFILES`.  If you need to support debhelper (<< 13.1~)
+    then you can set `DH_AUTOSCRIPTDIR` to a directory containing
+    the snippets instead (note it should point to the autoscripts
+    directory unlike `DH_DATAFILES`).
+
+  - (optional) A substitution parameter, which is one of 3 types:
+    - sed commands to run on the snippet, e.g. `s/#PACKAGE#/$PACKAGE/`.  
+      Note: Passed to the shell inside double quotes.
+    - a perl sub to invoke with `$_` set to each line of the snippet
+      in turn.
+    - a hashref, where each key will substitute `#${key}#` with the
+      value that `$key` points to.  [debhelper (>= 10.7)]
+
+  This command automatically adds shell script snippets to a debian
+  maintainer script (like the postinst or prerm).
+  Note that in v6 mode and up, the snippets are added in reverse
+  order for the removal scripts.
+
+- `autotrigger($package, $trigger_type, $trigger_target)`
+
+  This command automatically adds a trigger to the package.  The
+  parameters:
+  - binary package to be affected
+  - the type of trigger (e.g. "activate-noawait")
+  - the target (e.g. `ldconfig` or `/usr/share/foo`)
+
+- `dirname($pathname)`
+
+  Return directory part of pathname.
+
+- `basename($pathname)`
+
+  Return base of pathname,
+
+- `addsubstvar($package, $substvar, $deppackage, $verinfo, $remove)`
+
+  This function adds a dependency on some package to the specified
+  substvar in a package's substvar's file. It needs all these
+  parameters:
+  - binary package that gets the item
+  - name of the substvar to add the item to
+  - the package that will be depended on
+  - version info for the package (optional) (i.e. ">= 1.1")
+  - if this last parameter is passed, the thing that would be added
+    is removed instead. This can be useful to ensure that a debhelper
+    command is idempotent. (However, we generally don't bother,
+    and rely on the user calling `dh_prep`.) Note that without this
+    parameter, if you call the function twice with the same values it
+    will only add one item to the substvars file.
+
+- `delsubstvar($package, $substvar)`
+
+  This function removes the entire line for the substvar from the
+  package's shlibs file.
+
+- `excludefile($filename)`
+
+  This function returns true if `-X` has been used to ask for the file
+  to be excluded.
+
+- `is_udeb($package)`
+
+  Returns true if the package is marked as a udeb in the control
+  file.
+
+- `getpackages($type)`
+
+  Returns a list of packages in the control file.
+  Pass "arch" or "indep" to specify arch-dependent or
+  -independent. If `$type` is omitted, returns all
+  packages (including packages that are not built
+  for this architecture). Pass "both" to get the union
+  of "arch" and "indep" packages.  
+  Note that "both" is *not* the same omitting the `$type` parameter.  
+  As a side effect, populates `%package_arches` and `%package_types` with
+  the types of all packages (not only those returned).
+
+- `get_source_date_epoch()`
+
+  Return the value of `$ENV{SOURCE_DATE_EPOCH}` if exists.
+  Otherwise compute the value from the first changelog entry,
+  use it to set the ENV variable and return it.
+
+- `inhibit_log()`
+
+  Prevent logging the program's successful finish to
+  `debian/*debhelper.log`
+
+  Since debhelper 12.9, this can be done by passing the `inhibit_log`
+  option with a value of 1 to `init()` instead.  E.g.
+
+      init('inhibit_log' => 1);
+
+- `load_log($package, $hashref)`
+
+  Loads the log file for the given package and returns a list of
+  logged commands.
+  (Passing a hashref also causes it to populate the hash.)
+
+- `write_log($cmd, $package ...)`
+
+  Writes the log files for the specified package(s), adding
+  the cmd to the end.
+
+- `restore_file_on_clean($file)`
+
+  Store a copy of `$file`, which will be restored by `dh_clean`.
+  The `$file` *must* be a relative path to the package root and
+  *must* be a real regular file.  Dirs, devices and symlinks
+  (and everything else) *cannot* be restored by this.
+  If `$file` is passed multiple times (e.g. from different programs)
+  only the first version is stored.
+  CAVEAT: This *cannot* undo arbitrary "rm -fr"'ing.  The dir,
+  which the `$file` is/was in, must be present when `dh_clean` is
+  called.
+
+- `make_symlink($src, $dest, $tmp)`
+
+  Creates a Policy compliant system link called `$dest` pointing to
+  `$src`. If `$tmp` is given, then `$tmp` will be prefixed to `$dest`
+  when creating the actual symlink.
+
+- `install_dh_config_file($src, $dest)`
+
+  Installs `$src` into `$dest` using mode 0644.
+  If compat is 9 (or later) and `$src` is executable, `$src` will
+  be executed instead and its output will be used to generate the
+  `$dest` file.
+
+- `install_dir(@dirs)` / `mkdirs(@dirs)`
+
+  Create the directories denoted by the paths in `@dirs` and all
+  parent entries as well (as needed).  It uses mode 0755.
+  If a directory listed in `@dirs` already exists, the function
+  silently skips that directory (similar to `mkdir -p`).
+
+  The `install_dir` function should be used for directories
+  installed in a final package while `mkdirs` should be used
+  for other directories.  The difference is related to whether
+  the change will be shown via -v/--verbose or not.  The
+  `mkdirs` function requires `debhelper (>= 13.11~)`.
+
+- `install_file($src, $dest)`
+
+  Installs `$src` into `$dest` with mode 0644.  The parent dir of
+  `$dest` must exist (can be created with `install_dir`).
+  This is intended for installing regular non-executable files.
+
+- `install_prog($src, $dest)`
+
+  Installs `$src` into `$dest` with mode 0755.  The parent dir of
+  `$dest` must exist (can be created with `install_dir`).
+  This is intended for installing scripts or binaries.
+
+- `install_lib($src, $dest)`
+
+  Installs a library at the path `$src` into `$dest`.  The parent
+  dir of `$dest` must exist (can be created with `install_dir`).
+  This is intended for installing libraries.
+
+- `reset_perm_and_owner($mode, $path...)`
+
+  Resets the ownership and mode (POSIX permissions) of `$path`
+  This is useful for files created directly by the script, but
+  it not necessary for files installed via the `install_*`
+  functions.  
+  The file owner and group is set to "root:root".  The change
+  is only done on the exact paths listed (i.e. it is *not*
+  recursive).  
+  Mode should be passed as an integer (not a string).
+
+- `open_gz($file)`
+
+  Open `$file`, read from it as a gzip-compressed file and return
+  the file handle.
+  Depending on runtime features, it might be a pipe from an
+  external process (which will die with a "SIGPIPE" if you
+  do not consume all the input)
+
+- `deprecated_functionality($warn_msg[, $rm_compat[, $rm_msg]])`
+
+  Emit `$warn_msg` as a deprecation warning, or error out if `$rm_compat`
+  is provided and equal to (or greater than) the active compat level.
+  The `$rm_msg` parameter can be used to provide a custom error message
+  in the latter case (if omitted, `$warn_msg` will be used in both cases).
+  The function will provide a separate diagnostic about which compat
+  level that will remove/removed the functionality if `$rm_compat` is
+  given.
+
+- `log_installed_files($package, @paths)`
+
+  Creates a logfile (in `debian/.debhelper/generated`) for the helper's
+  processing of `$package`, which installed the files listed in
+  `@paths`. This logfile will later be used by the `dh_missing` helper.
+  Paths should be relative to the package root (i.e. the directory
+  containing `debian/`) and should not have superfluous segments
+  (e.g. avoid `foo/../bar` or `foo/./bar`).
+  If a directory is listed, it and all paths recursively beneath is
+  also considered installed.
+
+- `on_pkgs_in_parallel($code)` - prototype: (&)
+
+  Short hand for `on_items_in_parallel` with `$dh{DOPACKAGES}` as
+  as list of packages.
+
+- `on_items_in_parallel($item_list_ref, $code)`
+
+  Splits all the items in `$item_list_ref` into a number of groups
+  based on the max parallel (as decided by `DEB_BUILD_OPTIONS`)
+  A subprocess is forked for each group (minimum 1 process will be
+  forked) and each subprocess will be given a group of items
+  to process.  Each group is passed to the `$code` sub, which will
+  then process it and return normally on success.
+  Example:
+
+      my @all_packages = getpackages();
+      on_items_in_parallel(\@all_packages, sub {
+      	for my $package (@_) {
+      		my $tmp=tmpdir($package);
+      		my $pkgfile = pkgfile($package, 'foo');
+      		...;
+      	}
+      });
+      my @work_list = compute_work_list();
+      on_items_in_parallel(\@work_list, sub {
+      	for my $item (@_) {
+      		...;
+      	}
+      });
+
+  If there is an error, which should stop the build, please invoke
+  either `error()` or `error_exitcode`.  Alternatively, a trappable
+  error (e.g. `die($msg)`) can also be used.
+
+  Keep in mind that the sub will always be run in a subprocess,
+  so it cannot update global state.
+
+## Sequence Addons
+
+The [dh(1)] command has a `--with <addon>` parameter that can be used to load
+a sequence addon module named `Debian::Debhelper::Sequence::<addon>`.  
+These modules can add/remove commands to the dh command sequences, by
+calling some functions from `Dh_Lib`:
+
+- `insert_before($existing_command, $new_command)`
+
+  Insert `$new_command` in sequences before `$existing_command`
+
+  Compatible with "arch-only"/"indep-only" modes if the command
+  appears only in a compatible sequence.
+
+- `insert_after($existing_command, $new_command)`
+
+  Insert `$new_command` in sequences after `$existing_command`
+
+  Compatible with "arch-only"/"indep-only" modes if the command
+  appears only in a compatible sequence.
+
+- `remove_command($existing_command)`
+
+  Remove `$existing_command` from the list of commands to run
+  in all sequences.
+
+  Cannot be used in "arch-only"/"indep-only" mode.
+
+- `add_command($new_command, $sequence)`
+
+  Add `$new_command` to the beginning of the specified sequence.
+  If the sequence does not exist, it will be created.
+
+  Compatible with "arch-only"/"indep-only" modes if `$sequence`
+  is an "-arch" or "-indep" sequence (respectively).
+
+- `add_command_options($command, $opt1, $opt2, ...)`
+
+  Append `$opt1`, `$opt2` etc. to the list of additional options which
+  dh passes when running the specified `$command`. These options are
+  not relayed to debhelper commands called via `$command` override.
+
+  Cannot be used in "arch-only"/"indep-only" mode.
+
+- `remove_command_options($command)`
+
+  Clear all additional `$command` options previously added with
+  `add_command_options()`.
+
+  Cannot be used in "arch-only"/"indep-only" mode.
+
+- `remove_command_options($command, $opt1, $opt2, ...)`
+
+  Remove `$opt1`, `$opt2` etc. from the list of additional options which
+  dh passes when running the specified `$command`.
+
+  Cannot be used in "arch-only"/"indep-only" mode.
+
+- `declare_command_obsolete([$error_compat, ]$command)`
+
+  Declare `$command` as obsolete, which make dh warn about leftover
+  override / hook targets.  Note that `$command` *MUST NOT* be present
+  in the sequence!
+
+  The `$error_compat` parameter defines the compat level where
+  referencing this command via a hook target will become an error.
+  This must be at least 13 (which is the default if omitted).
+  Be careful with using already closed compat levels as error compat
+  for new commands as it will cause FTBFS.
+
+  Cannot be used in "arch-only"/"indep-only" mode.
+
+## Optimization techniques
+
+Most debhelper tools will have situations where they are not useful and can
+be skipped.  To support this, dh will look for a "NOOP PROMISE" as a part of
+a comment in the command before running it.  These promises have the form:
+
+    # PROMISE: DH NOOP WITHOUT pkgfile-logged(pkgfileA)  pkgfile-logged(pkgfileB) tmp(need/this) cli-options()
+
+The following keywords are defined:
+
+- `pkgfile(X)`: The command might do something if `debian/X` (or `debian/<package>.X`)
+  exist for any of the packages it will be run for. If the debhelper tool
+  interacts with `dh_missing`, you always want to use `pkgfile-logged(X)` instead.
+
+- `pkgfile-logged(X)`: Same as `pkgfile(X)` but it will also register which files
+  it handles so `dh_missing` can see it.
+
+- `tmp(X)`: The command might do something if `debian/<package>/X` exists.
+
+- `cli-options(--foo|--bar)`: The command might do something if *either* `--foo`
+  OR `--bar` are passed to the command.
+
+- `cli-options(BUILDSYSTEM)`: The command is a build system command (`dh_auto_*`)
+  and will react to standard build system command line options.
+
+- `cli-options()`: Special variant of `cli-options()` to declare that command
+  line options will not affect whether the tool will do something.  This enables
+  dh to skip commands even when passed custom options.  Without an explicit
+  `cli-option(...)` hint, dh will assume the command might react to it.
+
+If the hint is present and ALL of the keywords imply that the command can be
+skipped, dh will skip the command.
+
+## Logging helpers and dh_missing
+
+Since debhelper 10.3, debhelper has had a helper called `dh_missing`.  It
+takes over the `--list-missing` and `--fail-missing` options from `dh_install`
+and as the advantage that it can "see" what other helpers have installed.
+
+Under the hood, this works by the helpers logging the source files
+they (would) install to a hidden log file.  When `dh_missing` is called,
+it reads all these log files to determine which files have would been
+installed and compare them to what is present.
+
+If you are writing a helper that need to integrate with `dh_missing`,
+here is what you do:
+
+### Dh_Lib-based helpers
+
+- Replace `@{$dh{DOPACKAGES}}` with `getpackages()` and use
+  `process_pkg($package)` to determine if the helper should actually
+  install anything.
+- Call `log_installed_files` at least once per package (even on the ones
+  that are not to be acted on) with a list of source files that would be
+  installed.
+  - You can list entire directories even if there are files under
+    it that are ignored.
+  - Please call `log_installed_files` *even if* the list is empty for that
+    packages.  This enables `dh_missing` to see that the helper has been run
+    and nothing should be installed for that package.
+  - Prefer calling `log_installed_files` *exactly once* per package as
+    this is what it is optimized for.
+- If your helper has a `PROMISE`, it must use `pkgfile-logged(<file>)`
+  for its config files.  (See [#867246])
+  - CAVEAT: This requires a dependency on "debhelper (>= 10.2.5)".  Prior
+    to that version, debhelper will wrongly optimize your helper out.
+- Consider using `dh_installman` or `dh_installexamples` as examples.
+
+### Other helpers - via dh_assistant log-installed-files
+
+This process requires debhelper/13.10 or later.
+
+- The helper must compile a list of files it would have installed for
+  each package (even packages that are not acted on).  The file list
+  should be relative to the source package root (e.g.
+  `debian/tmp/usr/bin/bar`).
+  - This list can also contain directories.  They will be flagged as
+    installed along with their content (recursively).
+- Invoke `dh_assistant log-installed-files --on-behalf-of-cmd=${HELPER_NAME} -p${package} ${PATHS}`
+  - Invoking `dh_assistant` when your tool has no paths to log is
+    still recommended to let dh_missing that your tool had nothing
+    to record.
+  - Prefer calling `dh_assistant log-installed-files` *exactly once*
+    per package per invocation of your tool as this is what it is
+    optimized for.
+- If your helper has a PROMISE, it must use `pkgfile-logged(<file>)`
+  for its config files (see [#867246]).
+
+### Other helpers - manually
+
+- The helper must compile a list of files it would have installed for
+  each package (even packages that are not acted on).  The file list
+  should be relative to the source package root (e.g.
+  `debian/tmp/usr/bin/bar`).
+  - This list can also contain directories.  They will be flagged as
+    installed along with their content (recursively).
+- The helper must append to the file (create it if missing):
+     `debian/.debhelper/generated/${package}/installed-by-${HELPER_NAME}`
+  - Example: `debian/.debhelper/generated/lintian/installed-by-dh_install`
+  - The file should be created even if it is empty.  This enables `dh_missing`
+    to see that the helper has been run and nothing would be installed for
+    that package.
+- Please append to the file if it exists as the helper may be called multiple
+  times (once with `-a` and once with `-i`).  It is completely fine if this
+  leaves duplicate entries as dh_missing will deduplicate these.
+- If your helper has a PROMISE, it must use `pkgfile-logged(<file>)`
+  for its config files (see [#867246]).
+  CAVEAT: This requires a dependency on "debhelper (>= 10.2.5)".  Prior
+  to that version, debhelper will wrongly optimize your helper out.
+
+## Buildsystem Classes
+
+The `dh_auto_*` commands are frontends that use debhelper buildsystem
+classes. These classes have names like `Debian::Debhelper::Buildsystem::foo`,
+and are derived from `Debian::Debhelper::Buildsystem`, or other, related
+classes.
+
+A buildsystem class needs to inherit or define these methods: `DESCRIPTION`,
+`check_auto_buildable`, `configure`, `build`, `test`, `install`, `clean`. See
+the comments inside `Debian::Debhelper::Buildsystem` for details. Note that
+this interface is still subject to change.
+
+Note that third-party buildsystems will not automatically be used by
+default.  The package maintainer will either have to explicitly enable
+it via the `--buildsystem` parameter OR the build system should be
+registered in debhelper.  The latter is currently needed to ensure a
+stable and well-defined ordering of the build systems.
+
+[dh(1)]: https://manpages.debian.org/dh.1 "dh - debhelper command sequencer"
+[debhelper(7)]: https://manpages.debian.org/debhelper.7 "debhelper - the debhelper tool suite"
+[#867246]: https://bugs.debian.org/867246 "dh_installman incorrectly optimized away when using --fail-missing and building arch-any packages only"
+
+-- Joey Hess <joeyh@debian.org>
diff --git a/doc/SUPPORT-POLICY b/doc/SUPPORT-POLICY
new file mode 100644
index 00000000..9463e49f
--- /dev/null
+++ b/doc/SUPPORT-POLICY
@@ -0,0 +1,20 @@
+SUPPORT POLICY FOR DEBHELPER COMPAT LEVELS
+==========================================
+
+The current policy for supporting compat levels is:
+
+ * A compat level may be deprecated once the latest oldoldstable release
+   supports a /newer/ compat level.  (E.g. compat 9 can be deprecated once
+   jessie becomes oldoldstable).
+
+ * Alternatively, a compat level may be deprecated if a debhelper version
+   supporting a newer compat level is backported to oldoldstable-backports/
+   oldoldstable-backports-sloppy and the oldest supported Ubuntu LTS release.
+
+ * These rules are independent of whether Debian oldoldstable is still
+   supported.
+
+ * Deprecated compat levels may be removed in unstable once it as been released
+   in Debian stable as deprecated (provided that the deprecation has been
+   announced at least one year prior to the freeze of said stable release).
+
diff --git a/doc/TODO b/doc/TODO
index 822295fc..6da26db0 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -1,32 +1,20 @@
 v10:
 
 * escaping in config files (for whitespace)?
-* dh_installinit --restart-after-upgrade as default?
 
 Deprecated:
 
-* make a missing debian/compat an error. (started printing warning messages
-  in 20120115)
-* DH_COMPAT 1, 2, 3, 4. Can be removed once all packages are seen to be using
-  a newer version. I won't hold my breath. (2 and 3 are getting close though.)
-* dh_suidregister. Once nothing in the archive uses it.
 * dh_installmanpages.
 * dh_movefiles. I won't hold my breath. Have not added deprecation
   docs or message yet.
-* dh_undocumented
 * dh_installinit --init-script (make it warn)
 * dh_clean -k
-* dh_desktop, dh_scrollkeeper. Remove eventually..
 * -s flag, not formally deprecated yet; remove eventually
 * -u flag; add a warning on use and remove eventually
 * delsubstvar() and the last parameter to addsubstvar that makes it remove
   a string are not used in debhelper itself, but have been left in the
   library in case other things use them. Deprecate and remove.
-* dh --before , --after , --until , --remaining
 * debian/compress files
-* deprecate dh_gconf for dh_installgsettings (stuff should be migrating
-  away from gconf, and then I can just remove it -- have not added warning
-  or depreaction docs yet)
 
 Also, grep the entire archive for all dh_* command lines,
 and check to see what other switches are not being used, and maybe remove