Put newest compat level first in documentation

This is the same pattern as the Debian Policy Manual uses for its
checklist. It also optimizes for packages that are mostly up to date
(which is the most common case according to trends.d.n).

Signed-off-by: Niels Thykier <niels@thykier.net>

2 files changed, 404 insertions, 404 deletions

diff --git a/debhelper-compat-upgrade-checklist.pod b/debhelper-compat-upgrade-checklist.pod
index a4d16d5b..c55b1bd7 100644
--- a/debhelper-compat-upgrade-checklist.pod
+++ b/debhelper-compat-upgrade-checklist.pod
@@ -22,225 +22,354 @@ These are the available compatibility levels:
 
 =over 4
 
-=item v7
+=item v15
 
-This mode is deprecated.
+This compatibility level is still open for development; use with caution.
 
-This is the lowest supported compatibility level.
+Changes from v14 are:
 
-If you are upgrading from an earlier compatibility level, please
-review L<debhelper-obsolete-compat(7)>.
+=over 8
 
-=item v8
+=item -
 
-Changes from v7 are:
+The B<dh_auto_install> tool no longer defaults to B<< --destdir=debian/I<package> >>
+for source packages only producing a single binary.  If this behaviour is wanted,
+the package should explicitly activate the B<single-binary> dh addon (e.g., by adding
+B<dh-sequence-single-binary> to B<Build-Depends>) or pass B<--destdir> to
+B<dh_auto_install>.
+
+The rationale for this change to avoid "surprises" when adding a second binary package
+later.  Previously, debhelper would silently change behaviour often resulting in empty
+binary packages being uploaded to the archive by mistake. With the new behaviour,
+the B<single-binary> addon will detect the mismatch and warn the maintainer of what is
+about to happen.
+
+=back
+
+=item v14
+
+This compatibility level is still open for development; use with caution.
+
+Changes from v13 are:
 
 =over 8
 
 =item -
 
-Commands will fail rather than warning when they are passed unknown options.
+The B<cmake> buildsystem now passes
+B<-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON> to L<cmake(1)> to avoid some
+reproducibility issues.
 
 =item -
 
-B<dh_makeshlibs> will run B<dpkg-gensymbols> on all shared libraries that it
-generates shlibs files for. So B<-X> can be used to exclude libraries.
-Also, libraries in unusual locations that B<dpkg-gensymbols> would not
-have processed before will be passed to it, a behavior change that 
-can cause some packages to fail to build.
+The tool B<dh_installsysusers> is now included in the default sequence. This
+helper tool will process systemd sysusers files.
 
 =item -
 
-B<dh> requires the sequence to run be specified as the first parameter, and
-any switches come after it. Ie, use "B<dh $@ --foo>", not "B<dh --foo $@>".
+Use of the B<dh_gconf> command in override and hook targets now causes
+an error.  The B<dh_gconf> command has been a no-op for years and was
+removed in debhelper 13.4.
 
 =item -
 
-B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>.
+The B<dh> sequencer will warn if the B<single-binary> addon is implicitly activated to
+warn maintainers of the pending compat 15 change in B<dh_auto_install>.
+
+Maintainers are urged to either explicitly activate the B<single-binary> addon to
+preserve the existing behaviour (e.g., by adding B<dh-sequence-single-binary> to
+Build-Depends), or explicitly passing B<--destdir> to B<dh_auto_install> if used and
+then passing B<--without single-binary> to B<dh> (the latter to silence the warning).
+
+The rationale for this change to avoid "surprises" when adding a second binary package
+later.  Previously, debhelper would silently change behaviour often resulting in empty
+binary packages being uploaded to the archive by mistake. With the new behaviour,
+the B<single-binary> addon will detect the mismatch and warn the maintainer of what is
+about to happen.
+
+=item -
+
+The B<dh_installalternatives> tool will now be run after B<dh_link> rather than after
+B<dh_installinitramfs> in the default B<dh> sequence.
+
+=item -
+
+The B<dh_installpam> tool will now install PAM configuration files under
+F<< /usr/lib/pam.d/I<package> >> instead of F<< /etc/pam.d/I<package> >>.
+
+Please consider using the "rm_conffile" feature from
+L<dh_installdeb(1)> to ensure the proper removal of previous PAM files.
+
+=item -
+
+The B<meson+ninja> and B<cmake> build systems now use B<meson install> and
+B<cmake --install>, respectively, instead of B<ninja install> and B<make install>
+in the L<dh_auto_install(1)> call.  Any override of B<dh_auto_install> that
+passes extra parameters to the upstream build system should be reviewed.
 
 =back
 
-This mode is deprecated.
+=item v13
 
-=item v9
+This is the recommended mode of operation.
 
-Changes from v8 are:
+Changes from v12 are:
 
 =over 8
 
-=item - 
+=item -
 
-Multiarch support. In particular, B<dh_auto_configure> passes
-multiarch directories to autoconf in --libdir and --libexecdir.
+The B<meson+ninja> build system now uses B<meson test> instead of
+B<ninja test> when running the test suite.  Any override of
+B<dh_auto_test> that passes extra parameters to upstream test runner
+should be reviewed as B<meson test> is not command line compatible
+with B<ninja test>.
 
 =item -
 
-dh is aware of the usual dependencies between targets in debian/rules.
-So, "dh binary" will run any build, build-arch, build-indep, install,
-etc targets that exist in the rules file. There's no need to define an
-explicit binary target with explicit dependencies on the other targets.
+All debhelper like tools based on the official debhelper library
+(including B<dh> and the official B<dh_*> tools) no longer accepts
+abbreviated command parameters.  At the same time, B<dh> now
+optimizes out calls to redundant B<dh_*> helpers even when passed
+long command line options.
 
 =item -
 
-B<dh_strip> compresses debugging symbol files to reduce the installed
-size of -dbg packages.
+The ELF related debhelper tools (B<dh_dwz>, B<dh_strip>,
+B<dh_makeshlibs>, B<dh_shlibdeps>) are now only run for arch dependent
+packages by default (i.e. they are excluded from B<*-indep> targets
+and are passed B<-a> by default). If you need them for B<*-indep>
+targets, you can add an explicit Build-Depends on
+B<dh-sequence-elf-tools>.
 
 =item -
 
-B<dh_auto_configure> does not include the source package name
-in --libexecdir when using autoconf.
+The third-party B<gradle> build system (from B<gradle-debian-helper>
+package) now runs the upstream-provided test suite automatically.  To
+suppress such behavior, override B<dh_auto_test>.
 
 =item -
 
-B<dh> does not default to enabling --with=python-support
+The B<dh_installman> tool now aborts if it sees conflicting
+definitions of a manpage.  This typically happens if the upstream
+build system is installing a compressed version and the package lists
+an uncompressed version of the manpage in F<<
+debian/I<package>.manpages >>.  Often the easiest fix is to remove the
+manpage from F<< debian/I<package>.manpages >> (assuming both versions
+are identical).
 
-(Obsolete: As the B<dh_pysupport> tool was removed from Debian
-stretch.  Since debhelper/10.3, B<dh> no longer enables this sequence
-add-on regardless of compat level)
+=item -
+
+The B<dh_auto_*> helpers now reset the environment variables B<HOME>
+and common B<XDG_*> variable.  Please see description of the
+environment variables in L</ENVIRONMENT> for how this is handled.
+
+I<This feature changed between debhelper 13 and debhelper 13.2.>
 
 =item -
 
-All of the B<dh_auto_>I<*> debhelper programs and B<dh> set
-environment variables listed by B<dpkg-buildflags>, unless
-they are already set.
+The B<dh> command will now error if an override or hook target for an
+obsolete command are present in F<debian/rules>
+(e.g. B<override_dh_systemd_enable:>).
 
 =item -
 
-B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and
-LDFLAGS to perl F<Makefile.PL> and F<Build.PL>
+The B<dh_missing> command will now default to B<--fail-missing>.  This
+can be reverted to a non-fatal warning by explicitly passing
+B<--list-missing> like it was in compat 12.
+
+If you do not want the warning either, please omit the call to
+B<dh_missing>.  If you use the B<dh> command sequencer, then you can
+do this by inserting an empty override target in the
+F<debian/rules> file of the relevant package.  As an example:
+
+    # Disable dh_missing
+    override_dh_missing:
 
 =item -
 
-B<dh_strip> puts separated debug symbols in a location based on their
-build-id.
+The B<dh> command sequencer now runs B<dh_installtmpfiles> in the
+default sequence.  The B<dh_installtmpfiles> takes over handling of
+tmpfiles.d configuration files.  Related functionality in
+B<dh_installsystemd> is now disabled.
+
+Note that B<dh_installtmpfiles> responds to
+F<< debian/I<package>.tmpfiles >> where B<dh_installsystemd> used
+a name without the trailing "s".
 
 =item -
 
-Executable debhelper config files are run and their output used as the
-configuration.
+Many B<dh_*> tools now support limited variable expansion via the
+B<${foo}> syntax.  In many cases, this can be used to reference paths
+that contain either spaces or L<dpkg-architecture(1)> values.  While
+this can reduce the need for L<dh-exec(1)> in some cases, it is B<not>
+a replacement L<dh-exec(1)> in general.  If you need filtering,
+renaming, etc., the package will still need L<dh-exec(1)>.
 
-=back
+Please see L</Substitutions in debhelper config files> for syntax and
+available substitution variables.  To B<dh_*> tool writers, substitution
+expansion occurs as a part of the B<filearray> and B<filedoublearray>
+functions.
 
-This mode is deprecated.
+=item -
 
-=item v10
+The B<dh> command sequencer will now skip all hook and override targets
+for B<dh_auto_test>, B<dh_dwz> and B<dh_strip> when B<DEB_BUILD_OPTIONS>
+lists the relevant B<nocheck> / B<nostrip> options.
 
-Changes from v9 are:
+Any package relying on these targets to always be run should instead
+move relevant logic out of those targets.  E.g. non-test related
+packaging code from B<override_dh_auto_test> would have to be moved to
+B<execute_after_dh_auto_build> or B<execute_before_dh_auto_install>.
+
+=item -
+
+The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON>
+to L<cmake(1)> to speed up automatic installation process. If for some reason
+you need previous behavior, override the flag:
+
+    dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
+
+=back
+
+=item v12
+
+Changes from v11 are:
 
 =over 8
 
 =item -
 
-B<dh_installinit> will no longer install a file named debian/I<package>
-as an init script.
+The B<dh_makeshlibs> tool now generates shlibs files with versioned
+dependency by default.  This means that B<-VUpstream-Version>
+(a.k.a. B<-V>) is now the default.
+
+If an unversioned dependency in the shlibs file is wanted, this can be
+obtained by passing B<-VNone> instead.  However, please see
+L<dh_makeshlibs(1)> for the caveat of unversioned dependencies.
 
 =item -
 
-B<dh_installdocs> will error out if it detects links created with
---link-doc between packages of architecture "all" and non-"all" as it
-breaks binNMUs.
+The B<-s> (B<--same-arch>) option is removed.  Please use B<-a> (B<--arch>) instead.
 
 =item -
 
-B<dh_installdeb> no longer installs a maintainer-provided
-debian/I<package>.shlibs file.  This is now done by B<dh_makeshlibs>
-instead.
+Invoking B<dh_clean -k> now causes an error instead of a deprecation
+warning.
 
 =item -
 
-B<dh_installwm> refuses to create a broken package if no man page
-can be found (required to register for the x-window-manager alternative).
+The B<--no-restart-on-upgrade> option in B<dh_installinit> has been removed.
+Please use the new name B<--no-stop-on-upgrade>
 
 =item -
 
-Debhelper will default to B<--parallel> for all buildsystems that
-support parallel building.  This can be disabled by using either
-B<--no-parallel> or passing B<--max-parallel> with a value of 1.
+There was a bug in the B<doit> (and similar) functions from
+L<Debian::Debhelper::Dh_Lib> that made them spawn a shell in one
+particular circumstance.  This bug is now removed and will cause
+helpers that rely on the bug to fail with a "command not found"-error.
 
 =item -
 
-The B<dh> command will not accept any of the deprecated "manual
-sequence control" parameters (B<--before>, B<--after>, etc.).  Please
-use override targets instead.
+The B<--list-missing> and B<--fail-missing> in B<dh_install> has been
+removed.  Please use B<dh_missing> and its corresponding options,
+which can also see the files installed by other helpers.
 
-B<Retroactively applied to earlier compat levels>: B<dh> no longer
-accepts any of these since debhelper/12.4.
+=item -
+
+The B<dh_installinit> helper no longer installs configuration for
+the upstart init system.  Instead, it will abort the build if it
+finds an old upstart configuration file.  The error is there to
+remind the package maintainer to ensure the proper removal of the
+conffiles shipped in previous versions of the package (if any).
 
 =item -
 
-The B<dh> command will no longer use log files to track which commands
-have been run.  The B<dh> command I<still> keeps track of whether it
-already ran the "build" sequence and skip it if it did.
+The B<dh_installdeb> tool will do basic validation of some
+L<dpkg-maintscript-helper(1)> commands and will error out if the
+commands appear to be invalid.
 
-The main effects of this are:
+=item -
 
-=over 4
+The B<dh_missing> tool will now default to B<--list-missing>.
 
 =item -
 
-With this, it is now easier to debug the I<install> or/and I<binary>
-sequences because they can now trivially be re-run (without having to
-do a full "clean and rebuild" cycle)
+The B<dh_makeshlibs> tool will now only pass libraries to L<dpkg-gensymbols(1)>
+if the ELF binary has a SONAME (containing ".so").
 
 =item -
 
-The main caveat is that B<dh_*> now only keeps track of what happened
-in a single override target.  When all the calls to a given B<dh_cmd>
-command happens in the same override target everything will work as
-before.
+The B<dh_compress> tool no longer compresses examples (i.e. anything installed
+in F<</usr/share/doc/I<package>/examples>>.)
 
-Example of where it can go wrong:
+=item -
 
-  override_dh_foo:
-    dh_foo -pmy-pkg
+The standard sequence in B<dh> now includes B<dh_dwz> and
+B<dh_installinitramfs> by default.  This makes the B<dwz> and
+B<installinitramfs> sequences obsolete and they will now fail with an
+error.  If you want to skip these commands, then please insert an
+empty override target for them in F<debian/rules>
+(e.g. I<override_dh_dwz:>)
 
-  override_dh_bar:
-    dh_bar
-    dh_foo --remaining
+=item -
 
-In this case, the call to B<dh_foo --remaining> will I<also> include
-I<my-pkg>, since B<dh_foo -pmy-pkg> was run in a separate override
-target.  This issue is not limited to B<--remaining>, but also includes
-B<-a>, B<-i>, etc.
+The build systems B<meson> and B<autoconf> no longer explicitly set
+the B<--libexecdir> variable and thus relies on the build system
+default - which should be B</usr/libexec> (per FHS 3.0, adopted in
+Debian Policy 4.1.5).
 
-=back
+If a particular upstream package does not use the correct default, the
+parameter can often be passed manually via L<dh_auto_configure(1)>.  E.g.
+via the following example:
 
-=item -
+    override_dh_auto_configure:
+    	dh_auto_configure -- --libexecdir=/usr/libexec
 
-The B<dh_installdeb> command now shell-escapes the lines in the
-F<maintscript> config file.  This was the original intent but it did
-not work properly and packages have begun to rely on the incomplete
-shell escaping (e.g. quoting file names).
+Note the B<--> before the B<--libexecdir> parameter.
 
 =item -
 
-The B<dh_installinit> command now defaults to
-B<--restart-after-upgrade>.  For packages needing the previous
-behaviour, please use B<--no-restart-after-upgrade>.
+B<Retroactively removed in debhelper/13.5>:
+
+The B<dh_installdeb> tool would no longer installs the maintainer provided
+F<conffiles> file as it was deemed unnecessary.  However, the
+B<remove-on-upgrade> from dpkg/1.20 made the file relevant again and
+B<dh_installdeb> now installs it again in compat levels 12+.
 
 =item -
 
-The B<autoreconf> sequence is now enabled by default.  Please pass
-B<--without autoreconf> to B<dh> if this is not desirable for a given
-package
+The B<dh_installsystemd> tool no longer relies on B<dh_installinit> for
+handling systemd services that have a sysvinit alternative.  Both tools
+must now be used in such a case to ensure the service is properly started
+under both sysvinit and systemd.
+
+If you have an override for B<dh_installinit> (e.g. to call it with
+B<--no-start>) then you will probably need one for
+B<dh_installsystemd> as well now.
+
+This change makes B<dh_installinit> inject a I<misc:Pre-Depends> for
+B<< init-system-helpers (>= 1.54~) >>.  Please ensure that the package
+lists B<${misc:Pre-Depends}> in its B<Pre-Depends> field before
+upgrading to compat 12.
 
 =item -
 
-The B<systemd> sequence is now enabled by default.  Please pass
-B<--without systemd> to B<dh> if this is not desirable for a given
-package.
+The third-party B<dh_golang> tool (from B<dh-golang> package) now defaults on
+honoring B<DH_GOLANG_EXCLUDES> variable for source installation in -dev
+packages and not only during the building process. Please set
+B<DH_GOLANG_EXCLUDES_ALL> to false to revert to the previous behaviour. See
+B<Debian::Debhelper::Buildsystem::golang(3pm)> for details and examples.
 
 =item -
 
-B<Retroactively removed>: B<dh> no longer creates the package build
-directory when skipping running debhelper commands. This will not
-affect packages that only build with debhelper commands, but it may
-expose bugs in commands not included in debhelper.
+B<dh_installsystemduser> is now included in the B<dh> standard
+sequence by default.
 
-This compatibility feature had a bug since its inception in
-debhelper/9.20130516 that made it fail to apply in compat 9 and
-earlier.  As there has been no reports of issues caused by this bug in
-those ~5 years, this item have been removed rather than fixed.
+=item -
+
+The B<python-distutils> buildsystem is now removed.  Please use the
+third-party build system B<pybuild> instead.
 
 =back
 
@@ -397,356 +526,227 @@ This change may cause the tools to process more files than previously.
 
 =back
 
-=item v12
+=item v10
 
-Changes from v11 are:
+Changes from v9 are:
 
 =over 8
 
 =item -
 
-The B<dh_makeshlibs> tool now generates shlibs files with versioned
-dependency by default.  This means that B<-VUpstream-Version>
-(a.k.a. B<-V>) is now the default.
-
-If an unversioned dependency in the shlibs file is wanted, this can be
-obtained by passing B<-VNone> instead.  However, please see
-L<dh_makeshlibs(1)> for the caveat of unversioned dependencies.
-
-=item -
-
-The B<-s> (B<--same-arch>) option is removed.  Please use B<-a> (B<--arch>) instead.
+B<dh_installinit> will no longer install a file named debian/I<package>
+as an init script.
 
 =item -
 
-Invoking B<dh_clean -k> now causes an error instead of a deprecation
-warning.
+B<dh_installdocs> will error out if it detects links created with
+--link-doc between packages of architecture "all" and non-"all" as it
+breaks binNMUs.
 
 =item -
 
-The B<--no-restart-on-upgrade> option in B<dh_installinit> has been removed.
-Please use the new name B<--no-stop-on-upgrade>
+B<dh_installdeb> no longer installs a maintainer-provided
+debian/I<package>.shlibs file.  This is now done by B<dh_makeshlibs>
+instead.
 
 =item -
 
-There was a bug in the B<doit> (and similar) functions from
-L<Debian::Debhelper::Dh_Lib> that made them spawn a shell in one
-particular circumstance.  This bug is now removed and will cause
-helpers that rely on the bug to fail with a "command not found"-error.
+B<dh_installwm> refuses to create a broken package if no man page
+can be found (required to register for the x-window-manager alternative).
 
 =item -
 
-The B<--list-missing> and B<--fail-missing> in B<dh_install> has been
-removed.  Please use B<dh_missing> and its corresponding options,
-which can also see the files installed by other helpers.
+Debhelper will default to B<--parallel> for all buildsystems that
+support parallel building.  This can be disabled by using either
+B<--no-parallel> or passing B<--max-parallel> with a value of 1.
 
 =item -
 
-The B<dh_installinit> helper no longer installs configuration for
-the upstart init system.  Instead, it will abort the build if it
-finds an old upstart configuration file.  The error is there to
-remind the package maintainer to ensure the proper removal of the
-conffiles shipped in previous versions of the package (if any).
-
-=item -
+The B<dh> command will not accept any of the deprecated "manual
+sequence control" parameters (B<--before>, B<--after>, etc.).  Please
+use override targets instead.
 
-The B<dh_installdeb> tool will do basic validation of some
-L<dpkg-maintscript-helper(1)> commands and will error out if the
-commands appear to be invalid.
+B<Retroactively applied to earlier compat levels>: B<dh> no longer
+accepts any of these since debhelper/12.4.
 
 =item -
 
-The B<dh_missing> tool will now default to B<--list-missing>.
+The B<dh> command will no longer use log files to track which commands
+have been run.  The B<dh> command I<still> keeps track of whether it
+already ran the "build" sequence and skip it if it did.
 
-=item -
+The main effects of this are:
 
-The B<dh_makeshlibs> tool will now only pass libraries to L<dpkg-gensymbols(1)>
-if the ELF binary has a SONAME (containing ".so").
+=over 4
 
 =item -
 
-The B<dh_compress> tool no longer compresses examples (i.e. anything installed
-in F<</usr/share/doc/I<package>/examples>>.)
+With this, it is now easier to debug the I<install> or/and I<binary>
+sequences because they can now trivially be re-run (without having to
+do a full "clean and rebuild" cycle)
 
 =item -
 
-The standard sequence in B<dh> now includes B<dh_dwz> and
-B<dh_installinitramfs> by default.  This makes the B<dwz> and
-B<installinitramfs> sequences obsolete and they will now fail with an
-error.  If you want to skip these commands, then please insert an
-empty override target for them in F<debian/rules>
-(e.g. I<override_dh_dwz:>)
+The main caveat is that B<dh_*> now only keeps track of what happened
+in a single override target.  When all the calls to a given B<dh_cmd>
+command happens in the same override target everything will work as
+before.
 
-=item -
+Example of where it can go wrong:
 
-The build systems B<meson> and B<autoconf> no longer explicitly set
-the B<--libexecdir> variable and thus relies on the build system
-default - which should be B</usr/libexec> (per FHS 3.0, adopted in
-Debian Policy 4.1.5).
+  override_dh_foo:
+    dh_foo -pmy-pkg
 
-If a particular upstream package does not use the correct default, the
-parameter can often be passed manually via L<dh_auto_configure(1)>.  E.g.
-via the following example:
+  override_dh_bar:
+    dh_bar
+    dh_foo --remaining
 
-    override_dh_auto_configure:
-    	dh_auto_configure -- --libexecdir=/usr/libexec
+In this case, the call to B<dh_foo --remaining> will I<also> include
+I<my-pkg>, since B<dh_foo -pmy-pkg> was run in a separate override
+target.  This issue is not limited to B<--remaining>, but also includes
+B<-a>, B<-i>, etc.
 
-Note the B<--> before the B<--libexecdir> parameter.
+=back
 
 =item -
 
-B<Retroactively removed in debhelper/13.5>:
-
-The B<dh_installdeb> tool would no longer installs the maintainer provided
-F<conffiles> file as it was deemed unnecessary.  However, the
-B<remove-on-upgrade> from dpkg/1.20 made the file relevant again and
-B<dh_installdeb> now installs it again in compat levels 12+.
+The B<dh_installdeb> command now shell-escapes the lines in the
+F<maintscript> config file.  This was the original intent but it did
+not work properly and packages have begun to rely on the incomplete
+shell escaping (e.g. quoting file names).
 
 =item -
 
-The B<dh_installsystemd> tool no longer relies on B<dh_installinit> for
-handling systemd services that have a sysvinit alternative.  Both tools
-must now be used in such a case to ensure the service is properly started
-under both sysvinit and systemd.
-
-If you have an override for B<dh_installinit> (e.g. to call it with
-B<--no-start>) then you will probably need one for
-B<dh_installsystemd> as well now.
-
-This change makes B<dh_installinit> inject a I<misc:Pre-Depends> for
-B<< init-system-helpers (>= 1.54~) >>.  Please ensure that the package
-lists B<${misc:Pre-Depends}> in its B<Pre-Depends> field before
-upgrading to compat 12.
+The B<dh_installinit> command now defaults to
+B<--restart-after-upgrade>.  For packages needing the previous
+behaviour, please use B<--no-restart-after-upgrade>.
 
 =item -
 
-The third-party B<dh_golang> tool (from B<dh-golang> package) now defaults on
-honoring B<DH_GOLANG_EXCLUDES> variable for source installation in -dev
-packages and not only during the building process. Please set
-B<DH_GOLANG_EXCLUDES_ALL> to false to revert to the previous behaviour. See
-B<Debian::Debhelper::Buildsystem::golang(3pm)> for details and examples.
+The B<autoreconf> sequence is now enabled by default.  Please pass
+B<--without autoreconf> to B<dh> if this is not desirable for a given
+package
 
 =item -
 
-B<dh_installsystemduser> is now included in the B<dh> standard
-sequence by default.
+The B<systemd> sequence is now enabled by default.  Please pass
+B<--without systemd> to B<dh> if this is not desirable for a given
+package.
 
 =item -
 
-The B<python-distutils> buildsystem is now removed.  Please use the
-third-party build system B<pybuild> instead.
+B<Retroactively removed>: B<dh> no longer creates the package build
+directory when skipping running debhelper commands. This will not
+affect packages that only build with debhelper commands, but it may
+expose bugs in commands not included in debhelper.
 
-=back
+This compatibility feature had a bug since its inception in
+debhelper/9.20130516 that made it fail to apply in compat 9 and
+earlier.  As there has been no reports of issues caused by this bug in
+those ~5 years, this item have been removed rather than fixed.
 
-=item v13
+=back
 
-This is the recommended mode of operation.
+=item v9
 
-Changes from v12 are:
+Changes from v8 are:
 
 =over 8
 
 =item -
 
-The B<meson+ninja> build system now uses B<meson test> instead of
-B<ninja test> when running the test suite.  Any override of
-B<dh_auto_test> that passes extra parameters to upstream test runner
-should be reviewed as B<meson test> is not command line compatible
-with B<ninja test>.
-
-=item -
-
-All debhelper like tools based on the official debhelper library
-(including B<dh> and the official B<dh_*> tools) no longer accepts
-abbreviated command parameters.  At the same time, B<dh> now
-optimizes out calls to redundant B<dh_*> helpers even when passed
-long command line options.
-
-=item -
-
-The ELF related debhelper tools (B<dh_dwz>, B<dh_strip>,
-B<dh_makeshlibs>, B<dh_shlibdeps>) are now only run for arch dependent
-packages by default (i.e. they are excluded from B<*-indep> targets
-and are passed B<-a> by default). If you need them for B<*-indep>
-targets, you can add an explicit Build-Depends on
-B<dh-sequence-elf-tools>.
-
-=item -
-
-The third-party B<gradle> build system (from B<gradle-debian-helper>
-package) now runs the upstream-provided test suite automatically.  To
-suppress such behavior, override B<dh_auto_test>.
+Multiarch support. In particular, B<dh_auto_configure> passes
+multiarch directories to autoconf in --libdir and --libexecdir.
 
 =item -
 
-The B<dh_installman> tool now aborts if it sees conflicting
-definitions of a manpage.  This typically happens if the upstream
-build system is installing a compressed version and the package lists
-an uncompressed version of the manpage in F<<
-debian/I<package>.manpages >>.  Often the easiest fix is to remove the
-manpage from F<< debian/I<package>.manpages >> (assuming both versions
-are identical).
+dh is aware of the usual dependencies between targets in debian/rules.
+So, "dh binary" will run any build, build-arch, build-indep, install,
+etc targets that exist in the rules file. There's no need to define an
+explicit binary target with explicit dependencies on the other targets.
 
 =item -
 
-The B<dh_auto_*> helpers now reset the environment variables B<HOME>
-and common B<XDG_*> variable.  Please see description of the
-environment variables in L</ENVIRONMENT> for how this is handled.
-
-I<This feature changed between debhelper 13 and debhelper 13.2.>
+B<dh_strip> compresses debugging symbol files to reduce the installed
+size of -dbg packages.
 
 =item -
 
-The B<dh> command will now error if an override or hook target for an
-obsolete command are present in F<debian/rules>
-(e.g. B<override_dh_systemd_enable:>).
+B<dh_auto_configure> does not include the source package name
+in --libexecdir when using autoconf.
 
 =item -
 
-The B<dh_missing> command will now default to B<--fail-missing>.  This
-can be reverted to a non-fatal warning by explicitly passing
-B<--list-missing> like it was in compat 12.
-
-If you do not want the warning either, please omit the call to
-B<dh_missing>.  If you use the B<dh> command sequencer, then you can
-do this by inserting an empty override target in the
-F<debian/rules> file of the relevant package.  As an example:
+B<dh> does not default to enabling --with=python-support
 
-    # Disable dh_missing
-    override_dh_missing:
+(Obsolete: As the B<dh_pysupport> tool was removed from Debian
+stretch.  Since debhelper/10.3, B<dh> no longer enables this sequence
+add-on regardless of compat level)
 
 =item -
 
-The B<dh> command sequencer now runs B<dh_installtmpfiles> in the
-default sequence.  The B<dh_installtmpfiles> takes over handling of
-tmpfiles.d configuration files.  Related functionality in
-B<dh_installsystemd> is now disabled.
-
-Note that B<dh_installtmpfiles> responds to
-F<< debian/I<package>.tmpfiles >> where B<dh_installsystemd> used
-a name without the trailing "s".
+All of the B<dh_auto_>I<*> debhelper programs and B<dh> set
+environment variables listed by B<dpkg-buildflags>, unless
+they are already set.
 
 =item -
 
-Many B<dh_*> tools now support limited variable expansion via the
-B<${foo}> syntax.  In many cases, this can be used to reference paths
-that contain either spaces or L<dpkg-architecture(1)> values.  While
-this can reduce the need for L<dh-exec(1)> in some cases, it is B<not>
-a replacement L<dh-exec(1)> in general.  If you need filtering,
-renaming, etc., the package will still need L<dh-exec(1)>.
-
-Please see L</Substitutions in debhelper config files> for syntax and
-available substitution variables.  To B<dh_*> tool writers, substitution
-expansion occurs as a part of the B<filearray> and B<filedoublearray>
-functions.
+B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and
+LDFLAGS to perl F<Makefile.PL> and F<Build.PL>
 
 =item -
 
-The B<dh> command sequencer will now skip all hook and override targets
-for B<dh_auto_test>, B<dh_dwz> and B<dh_strip> when B<DEB_BUILD_OPTIONS>
-lists the relevant B<nocheck> / B<nostrip> options.
-
-Any package relying on these targets to always be run should instead
-move relevant logic out of those targets.  E.g. non-test related
-packaging code from B<override_dh_auto_test> would have to be moved to
-B<execute_after_dh_auto_build> or B<execute_before_dh_auto_install>.
+B<dh_strip> puts separated debug symbols in a location based on their
+build-id.
 
 =item -
 
-The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON>
-to L<cmake(1)> to speed up automatic installation process. If for some reason
-you need previous behavior, override the flag:
-
-    dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
+Executable debhelper config files are run and their output used as the
+configuration.
 
 =back
 
-=item v14
+This mode is deprecated.
 
-This compatibility level is still open for development; use with caution.
+=item v8
 
-Changes from v13 are:
+Changes from v7 are:
 
 =over 8
 
 =item -
 
-The B<cmake> buildsystem now passes
-B<-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON> to L<cmake(1)> to avoid some
-reproducibility issues.
-
-=item -
-
-The tool B<dh_installsysusers> is now included in the default sequence. This
-helper tool will process systemd sysusers files.
-
-=item -
-
-Use of the B<dh_gconf> command in override and hook targets now causes
-an error.  The B<dh_gconf> command has been a no-op for years and was
-removed in debhelper 13.4.
-
-=item -
-
-The B<dh> sequencer will warn if the B<single-binary> addon is implicitly activated to
-warn maintainers of the pending compat 15 change in B<dh_auto_install>.
-
-Maintainers are urged to either explicitly activate the B<single-binary> addon to
-preserve the existing behaviour (e.g., by adding B<dh-sequence-single-binary> to
-Build-Depends), or explicitly passing B<--destdir> to B<dh_auto_install> if used and
-then passing B<--without single-binary> to B<dh> (the latter to silence the warning).
-
-The rationale for this change to avoid "surprises" when adding a second binary package
-later.  Previously, debhelper would silently change behaviour often resulting in empty
-binary packages being uploaded to the archive by mistake. With the new behaviour,
-the B<single-binary> addon will detect the mismatch and warn the maintainer of what is
-about to happen.
+Commands will fail rather than warning when they are passed unknown options.
 
 =item -
 
-The B<dh_installalternatives> tool will now be run after B<dh_link> rather than after
-B<dh_installinitramfs> in the default B<dh> sequence.
+B<dh_makeshlibs> will run B<dpkg-gensymbols> on all shared libraries that it
+generates shlibs files for. So B<-X> can be used to exclude libraries.
+Also, libraries in unusual locations that B<dpkg-gensymbols> would not
+have processed before will be passed to it, a behavior change that
+can cause some packages to fail to build.
 
 =item -
 
-The B<dh_installpam> tool will now install PAM configuration files under
-F<< /usr/lib/pam.d/I<package> >> instead of F<< /etc/pam.d/I<package> >>.
-
-Please consider using the "rm_conffile" feature from
-L<dh_installdeb(1)> to ensure the proper removal of previous PAM files.
+B<dh> requires the sequence to run be specified as the first parameter, and
+any switches come after it. Ie, use "B<dh $@ --foo>", not "B<dh --foo $@>".
 
 =item -
 
-The B<meson+ninja> and B<cmake> build systems now use B<meson install> and
-B<cmake --install>, respectively, instead of B<ninja install> and B<make install>
-in the L<dh_auto_install(1)> call.  Any override of B<dh_auto_install> that
-passes extra parameters to the upstream build system should be reviewed.
+B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>.
 
 =back
 
-=item v15
-
-This compatibility level is still open for development; use with caution.
-
-Changes from v14 are:
-
-=over 8
+This mode is deprecated.
 
-=item -
+=item v7
 
-The B<dh_auto_install> tool no longer defaults to B<< --destdir=debian/I<package> >>
-for source packages only producing a single binary.  If this behaviour is wanted,
-the package should explicitly activate the B<single-binary> dh addon (e.g., by adding
-B<dh-sequence-single-binary> to B<Build-Depends>) or pass B<--destdir> to
-B<dh_auto_install>.
+This mode is deprecated.
 
-The rationale for this change to avoid "surprises" when adding a second binary package
-later.  Previously, debhelper would silently change behaviour often resulting in empty
-binary packages being uploaded to the archive by mistake. With the new behaviour,
-the B<single-binary> addon will detect the mismatch and warn the maintainer of what is
-about to happen.
+This is the lowest supported compatibility level.
 
-=back
+If you are upgrading from an earlier compatibility level, please
+review L<debhelper-obsolete-compat(7)>.
 
 =back
 
diff --git a/debhelper-obsolete-compat.pod b/debhelper-obsolete-compat.pod
index c5626677..965c8947 100644
--- a/debhelper-obsolete-compat.pod
+++ b/debhelper-obsolete-compat.pod
@@ -18,69 +18,63 @@ changes.
 
 =over 4
 
-=item v1
-
-This is the original debhelper compatibility level, and so it is the default
-one. In this mode, debhelper will use F<debian/tmp> as the package tree
-directory for the first binary package listed in the control file, while using
-debian/I<package> for all other packages listed in the F<control> file.
-
-This mode is deprecated.
-
-=item v2
+=item v7
 
-In this mode, debhelper will consistently use debian/I<package>
-as the package tree directory for every package that is built.
+This is the lowest supported compatibility level.
 
-This mode is deprecated.
+Changes from v6 are:
 
-=item v3
+=over 8
 
-This mode works like v2, with the following additions:
+=item -
 
-=over 8
+B<dh_install>, will fall back to looking for files in F<debian/tmp> if it doesn't
+find them in the current directory (or wherever you tell it look using
+B<--sourcedir>). This allows B<dh_install> to interoperate with B<dh_auto_install>,
+which installs to F<debian/tmp>, without needing any special parameters.
 
 =item -
 
-Debhelper config files support globbing via B<*> and B<?>, when appropriate. To
-turn this off and use those characters raw, just prefix with a backslash.
+B<dh_clean> will read F<debian/clean> and delete files listed there.
 
 =item -
 
-B<dh_makeshlibs> makes the F<postinst> and F<postrm> scripts call B<ldconfig>.
+B<dh_clean> will delete toplevel F<*-stamp> files.
 
 =item -
 
-Every file in F<etc/> is automatically flagged as a conffile by B<dh_installdeb>.
+B<dh_installchangelogs> will guess at what file is the upstream changelog if
+none is specified.
 
 =back
 
-This mode is deprecated.
-
-=item v4
+=item v6
 
-Changes from v3 are:
+Changes from v5 are:
 
 =over 8
 
 =item -
 
-B<dh_makeshlibs -V> will not include the Debian part of the version number in
-the generated dependency line in the shlibs file.
+Commands that generate maintainer script fragments will order the
+fragments in reverse order for the F<prerm> and F<postrm> scripts.
 
 =item -
 
-You are encouraged to put the new B<${misc:Depends}> into F<debian/control> to
-supplement the B<${shlibs:Depends}> field.
+B<dh_installwm> will install a slave manpage link for F<x-window-manager.1.gz>,
+if it sees the man page in F<usr/share/man/man1> in the package build
+directory.
 
 =item -
 
-B<dh_fixperms> will make all files in F<bin/> directories and in F<etc/init.d>
-executable.
+B<dh_builddeb> did not previously delete everything matching
+B<DH_ALWAYS_EXCLUDE>, if it was set to a list of things to exclude, such as
+B<CVS:.svn:.git>. Now it does.
 
 =item -
 
-B<dh_link> will correct existing links to conform with policy.
+B<dh_installman> allows overwriting existing man pages in the package build
+directory. In previous compatibility levels it silently refuses to do this.
 
 =back
 
@@ -111,67 +105,73 @@ B<dh_install> errors out if wildcards expand to nothing.
 
 =back
 
-=item v6
+=item v4
 
-Changes from v5 are:
+Changes from v3 are:
 
 =over 8
 
 =item -
 
-Commands that generate maintainer script fragments will order the
-fragments in reverse order for the F<prerm> and F<postrm> scripts.
+B<dh_makeshlibs -V> will not include the Debian part of the version number in
+the generated dependency line in the shlibs file.
 
 =item -
 
-B<dh_installwm> will install a slave manpage link for F<x-window-manager.1.gz>,
-if it sees the man page in F<usr/share/man/man1> in the package build
-directory.
+You are encouraged to put the new B<${misc:Depends}> into F<debian/control> to
+supplement the B<${shlibs:Depends}> field.
 
 =item -
 
-B<dh_builddeb> did not previously delete everything matching
-B<DH_ALWAYS_EXCLUDE>, if it was set to a list of things to exclude, such as
-B<CVS:.svn:.git>. Now it does.
+B<dh_fixperms> will make all files in F<bin/> directories and in F<etc/init.d>
+executable.
 
 =item -
 
-B<dh_installman> allows overwriting existing man pages in the package build
-directory. In previous compatibility levels it silently refuses to do this.
+B<dh_link> will correct existing links to conform with policy.
 
 =back
 
 This mode is deprecated.
 
-=item v7
-
-This is the lowest supported compatibility level.
+=item v3
 
-Changes from v6 are:
+This mode works like v2, with the following additions:
 
 =over 8
 
 =item -
 
-B<dh_install>, will fall back to looking for files in F<debian/tmp> if it doesn't
-find them in the current directory (or wherever you tell it look using
-B<--sourcedir>). This allows B<dh_install> to interoperate with B<dh_auto_install>,
-which installs to F<debian/tmp>, without needing any special parameters.
+Debhelper config files support globbing via B<*> and B<?>, when appropriate. To
+turn this off and use those characters raw, just prefix with a backslash.
 
 =item -
 
-B<dh_clean> will read F<debian/clean> and delete files listed there.
+B<dh_makeshlibs> makes the F<postinst> and F<postrm> scripts call B<ldconfig>.
 
 =item -
 
-B<dh_clean> will delete toplevel F<*-stamp> files.
+Every file in F<etc/> is automatically flagged as a conffile by B<dh_installdeb>.
 
-=item -
+=back
 
-B<dh_installchangelogs> will guess at what file is the upstream changelog if
-none is specified.
+This mode is deprecated.
 
-=back
+=item v2
+
+In this mode, debhelper will consistently use debian/I<package>
+as the package tree directory for every package that is built.
+
+This mode is deprecated.
+
+=item v1
+
+This is the original debhelper compatibility level, and so it is the default
+one. In this mode, debhelper will use F<debian/tmp> as the package tree
+directory for the first binary package listed in the control file, while using
+debian/I<package> for all other packages listed in the F<control> file.
+
+This mode is deprecated.
 
 =back