Bug#728200: debian-policy: force build tools to ensure source trees are build-ready

[Julian Gilbey <julian@d-and-j.net>]

On Tue, Oct 29, 2013 at 01:25:57PM +0000, Ximin Luo wrote:
> Not having to support "patch" greatly simplifies things, but "deprecation" is not mentioned anywhere in Section 4... Do you know how many existing packages still use "patch"?

That's a good point: with the not-so-recent introduction of the
recommended source format 3.0 (quilt) for non-native packages, there
should probably be two changes:

* In section 4.9, the `patch' target should be labelled as
  (deprecated) instead of (optional), and the wording of the paragraph
  updated to something like:

    This now-deprecated optional target performs whatever additional
    actions are required to make the source ready for editing
    (unpacking additional upstream archives, applying patches, etc.).
    It was previously recommended to be implemented for any package
    where `dpkg-source -x' does not result in source ready for
    additional modification.  However, when using source format 3.0
    (quilt), all of this is now done automatically by `dpkg-source
    -x', so there should be no need for a separate `patch' target.
    Also see Section 4.14, `Source package handling:
    `debian/README.source''.

* In section 4.14, the opening part could be reworded as follows.
  Note also a clarification to the wording of point 3 below:

    In general, when using source format 3.0 (quilt) or later, running
    `dpkg-source -x' on a source package will produce the source of
    the package, ready for editing.  This will allow one to make
    changes and run `dpkg-buildpackage' to produce a modified package
    without taking any additional steps.  (Note, however, that such
    modifications must be made in the form of a new patch using the
    `quilt' system with QUILT_PATCHES=debian/patches, otherwise
    `dpkg-source -b' will fail.)

    If other steps are required to produce a source package ready for
    editing, creating a `debian/README.source' documentation file is
    recommended.  This file should explain how to do all of the
    following:

    1.  Generate the fully patched source, in a form ready for
        editing, that would be built to create Debian packages.  In
        general, this should be automatically achieved by running
        `dpkg-source -x', but if not, this should be documented.
        There used to be an optional `patch' target in `debian/rules'
        for this purpose; see Section 4.9, `Main building script:
        `debian/rules''.

    2.  Modify the source and save those modifications so that they
        will be applied when building the package.

    3.  Remove source modifications that are currently being applied.

    4.  Optionally, document what steps are necessary to upgrade the
        Debian source package to a new upstream version, if
        applicable.


   Julian