maint-guide updates (take 2)

[Osamu Aoki <osamu@debian.org>]

Thanks Jastin but ... situation is a bit different

    <p>If the build directory checked out from upstream's VCS repository contains
    unpatched upstream source with a <file>debian/*</file> tree for the Debian
    packaging, and you want to keep it clean after a package build, you should
    create the optional <file>debian/source/local-options</file> file in it
    containing "<tt>--unapply-patches</tt>".  This file is not included in the
    generated source package and changes the local build behavior only (see
    <manref name="dpkg-source" section="1">).

This is not the case.  (Upstream may have debian/* but that is not used
for packaging except as a reference point for the maintainer.)  This
confusion calls for my rewrite :-)

This is a VCS where it tracks upstream source in one branch and also has
debian branch which adds files in <file>debian/*</file>.  Maybe we need
to start from there.  This is how many people use VCS for Debian
packaging activities.

Let me redo this with a whole new text.

  <p>When you want to manage Debian packaging activities under a VCS, you
  typically create one branch (e.g. <tt>upstream</tt>) tracking the
  upstream source and another branch (e.g. <tt>main</tt>) tracking the
  Debian package.  For the <tt>main</tt> branch, you usually want to have
  unpatched upstream source with <file>debian/*</file> files for the
  Debian packaging for the ease of merging new upstream releases.
  
  <p>After building a package, the source is normally left patched.  You
  need to unpatch it manually by running "<tt>quilt pop -a</tt>" before
  committing to the <tt>main</tt> branch.  You can automate this unpatch
  by adding the optional <file>debian/source/local-options</file> file
  containing "<tt>--unapply-patches</tt>".  This file is not included in
  the generated source package and changes the local build behavior only
  (see <manref name="dpkg-source" section="1">).

Any comment?

(I do not want to write extensively on how VCS is used.  There can be
many optoins.  As long as enough hints are given for
<file>debian/source/local-options</file> file, it is good enough as
maint-guide content.  People can read manpage, anyway.)

Osamu

PS:  I am now subscribed.