[debhelper-devel] Bug#765446: debhelper build target status file packagename.debhelper.log is not documented

[Mikko Rapeli]

Package: debhelper
Version: 9.20120909
Severity: minor
Tags: patch

Dear Maintainer,

debhelper build status log file is not documented in manual pages.
Common developer use cases involve modifying list of installed files
and package install scripts, and for these use cases a complete re-compile
of the packages in not necessary. Instead developers could modify
the package status log to re-execute all steps after build target, for example.

Here's the kind of documentation I had in mind (on top of debhelper
git master):

>From 275c394597c9ab8dff3a5e8fe9de8bf49c66ba41 Mon Sep 17 00:00:00 2001
From: Mikko Rapeli <mikko.rapeli at iki.fi>
Date: Wed, 15 Oct 2014 10:36:56 +0300
Subject: [PATCH] Document build status file

It is useful to change just the build status file when only some of the build
steps need to be re-executed, e.g. after changes to .install files.

Rename SEE ALSO to EXAMPLES because that's what they are.

Signed-off-by: Mikko Rapeli <mikko.rapeli at iki.fi>
---
 debhelper.pod |   16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/debhelper.pod b/debhelper.pod
index 659c4a3..0032892 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -689,7 +689,21 @@ B<DH_ALWAYS_EXCLUDE=CVS:.svn>
 
 =back
 
-=head1 SEE ALSO
+=head1 BUILD TARGET STATUS LOG
+
+debhelper maintains build state in F<debian/packagename.debhelper.log> file.
+This file contains an entry for all successfully executed build targets
+after package compilation.
+
+A common usecase for developers is to change list of installed files
+via F<debian/packagename.install> or package install scripts. With these cases
+it is not necessary to recompile the whole package but instead only build steps
+after normal source tree compilation need to be re-executed. This is achieved
+my removing all lines after dh_auto_build in F<debian/packagename.debhelper.log>
+file and recompiling the package with 'fakeroot debian/rules binary' or
+debuild.
+
+=head1 EXAMPLES
 
 =over 4
 
-- 
1.7.10.4


-- System Information:
Debian Release: 7.6
  APT prefers stable-updates
  APT policy: (500, 'stable-updates'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 3.2.58-grbfs-kapsi (SMP w/24 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages debhelper depends on:
ii  binutils    2.22-8
ii  dpkg        1.16.15
ii  dpkg-dev    1.16.15
ii  file        5.11-2+deb7u5
ii  html2text   1.3.2a-15
ii  man-db      2.6.2-1
ii  perl        5.14.2-21+deb7u1
ii  po-debconf  1.0.16+nmu2

debhelper recommends no packages.

Versions of packages debhelper suggests:
ii  dh-make  0.61

-- no debconf information