Bug#930666: Please document consensus on use of dh sequencer

[Russ Allbery <rra@debian.org>]

Here is an updated patch incorporating Sean's wording changes as well as
other changes discussed elsewhere on the thread.  This reverts most of my
unrelated informative changes for clarity (they can be discussed or made
separately) and drops the sample dh makefile in favor of just referencing
the debhelper documentation.  It does keep some minor wording and
formatting fixes in the first two paragraphs.

This also removes the word "new" from the discussion of using another
packaging helper as an example, to make it a bit more obvious that the
cdbs maintainer using cdbs is one of the expected exceptions.

diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index ee9270d..93beb4a 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -259,13 +259,33 @@ files, sockets or setuid or setgid files.. [#]_
 Main building script: ``debian/rules``
 --------------------------------------
 
-This file must be an executable makefile, and contains the
-package-specific recipes for compiling the package and building binary
-package(s) from the source.
-
-It must start with the line ``#!/usr/bin/make -f``, so that it can be
-invoked by saying its name rather than invoking ``make`` explicitly.
-That is, invoking either of ``make -f debian/rules args...`` or ``./debian/rules args...`` must result in identical behavior.
+This file must be an executable makefile.  It contains the
+package-specific recipes for compiling the source (if required) and
+constructing one or more binary packages.
+
+``debian/rules`` must start with the line ``#!/usr/bin/make -f``, so that
+it can be invoked by saying its name rather than invoking ``make``
+explicitly.  That is, invoking either of ``make -f debian/rules args...``
+or ``./debian/rules args...`` must result in identical behavior.
+
+The recommended way to implement the build process of a Debian package, in
+the absence of a good reason to use a different approach, is the ``dh``
+tool.  This includes the contents of the ``debian/rules`` building script.
+``dh`` is the most common packaging helper tool in Debian.  Using it will
+usually save effort in complying with the rules in this document, because
+``dh`` will automatically implement many of them without requiring
+explicit instructions.
+
+There are sometimes good reasons to use a different approach.  For
+example, the standard tools for packaging software written in some
+languages may use another tool; some rarer packaging patterns, such as
+multiple builds of the same software with different options, are easier to
+express with other tools; and a packager working on a different packaging
+helper might want to use their tool.  The recommendation to use ``dh``
+does not always apply, and use of ``dh`` is not required.
+
+For more information about how to use ``dh``, see the documentation in the
+debhelper package, most notably the dh(1) manual page.
 
 The following targets are required and must be implemented by
 ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>