doc/v3

   1 Debhelper v3 is a major new revision of debhelper. Currently, v3 is still
   2 being worked on, and will change in drastic ways without notice. This
   3 *will* break packages that use it, so don't, unless you like riding the
   4 bleeding edge.
   5
   6 To enable debhelper v3 features (do this with *caution*), set DH_COMPAT=3 in
   7 your debian/rules. Also, it is a very good idea to add a call to your
   8 debian/rules like this:
   9         dh_testversion 2
  10 To ensure that your package won't be built with some old version of
  11 debhelper that ignores the DH_COMPAT flag.
  12
  13 Here are the changes I'm planning to make to debhelper for v3, based on
  14 prior discussion on debian-devel.
  15
  16 Items marked with a + are done. All others will happen as soon as I can code
  17 them.
  18
  19 * dh_installmanpages will be made into a non-DWIM program, so you'll have to
  20   specify all man pages to install and possibly where to put them. This may
  21   look something like:
  22         dh_installmanpages -x xterm.1 xfoo.1 xbar.man
  23         dh_installmanpages --section=8 su.man
  24   Ok, there's a _little_ DWIM left in there, it'll be smart enough to munge
  25   the .man filenames properly. It'll probably just assume all man pages have
  26   an  extension, and delete that extentation, and add the correct one.
  27
  28 * dh_movefiles will use a name other than debian/<package>.files for the
  29   list of what to move, because it can't use debian/files for the first
  30   package, since that file is already used elsewhere. It'll use
  31   debian/<package>.move
  32
  33 * dh_movefiles should delete empty directories after it's moved all files
  34   out of them. (#17111)
  35
  36 * debian/README will be installed as /usr/share/doc/<package>/README in
  37   native packages, and as README.Debian in non-native packages. This is
  38   consistent with the handing of debian/TODO and debian/changelog. (#34628)
  39
  40 * There will be no change to the names of debhelper config files used, I've
  41   decided against debian/<package>/* and the like, because although those
  42   subdirs do work, they're not allowed by the packaging manual, and they'd
  43   make source unpacking by hand a lot harder. I will leave these files
  44   completly as they are now. However, I will remove most of the language
  45   documenting that debian/<foo> works, and will deprecate that usage.
  46   debian/<package>.<foo> will be preferred even in single binary packages.
  47
  48 * Every file in etc/ will be automatically be flagged as a conffile.
  49
  50 * Debhelper config files will support globbing via * and ?, when
  51   appropriate. To turn this off and use those changarcters raw, just quote
  52   them.
  53
  54 * dh_makeshlibs will generate autoscript fragments for ldconfig. This will
  55   require you call it before dh_installdeb, which isn't always done now.
  56