After extensive discussion in Bug#250202 and elsewhere on how to handle
the increasing variety of different build and patch systems in Debian, the
consensus on the debian-policy list is to recommend adding a new
documentation file, debian/README.source, to any Debian source package
with a complex build system. The precise definition of "complex" is a
package where one one cannot unpack the source package with dpkg-source -x
and immediately get the source that would be built without running further
commands or where additional steps must be taken to incorporate changes
beyond just modifying files.
This new recommendation is *not* RC for lenny, only a recommendation.
However, it is still a recommendation that most affected packages don't
currently follow, so I wanted to give the development community a heads-up
on this change.
The specific new wording is:
4.14. Source package handling: `debian/README.source'
-----------------------------------------------------
If running `dpkg-source -x' on a source package doesn't produce the
source of the package, ready for editing, and allow one to make
changes and run `dpkg-buildpackage' to produce a modified package
without taking any additional steps, 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. Doing this with a
`patch' target in `debian/rules' is recommended; 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 when
building the package.
4. Optionally, document what steps are necessary to upgrade the
Debian source package to a new upstream version, if applicable.
This explanation should include specific commands and mention any
additional required Debian packages. It should not assume familiarity
with any specific Debian packaging system or patch management tools.
This explanation may refer to a documentation file installed by one of
the package's build dependencies provided that the referenced
documentation clearly explains these tasks and is not a general
reference manual.
`debian/README.source' may also include any other information that
would be helpful to someone modifying the source package. Even if the
package doesn't fit the above description, maintainers are encouraged
to document in a `debian/README.source' file any source package with a
particularly complex or unintuitive source layout or build system (for
example, a package that builds the same source multiple times to
generate different binary packages).
This change will be in the next Debian Policy upload unless there is some
significant change in the consensus. Hence, if you think this is a bad
idea (after reviewing the previous discussion), please raise objections
*now* in Bug#250202. Please do review the previous discussion first.
Patch system maintainers may want to consider including such documentation
in the next upload so that packages that use that patch system can refer
to the existing documentation rather than provide their own. Maintainers
of packages that use a standard patch system may want to hold off on
adding a README.source until there is a standard document for that patch
system to refer to.
Here is a sample of the sort of documentation that would satisfy this
recommendation, written for a package that's using quilt:
---8<---
This package uses quilt to manage all modifications to the upstream
source. Changes are stored in the source package as diffs in
debian/patches and applied during the build.
To get the fully patched source after unpacking the source package, cd to
the root level of the source package and run:
quilt push -a
The last patch listed in debian/patches/series will become the current
patch.
To add a new set of changes, first run quilt push -a, and then run:
quilt new <patch>
where <patch> is a descriptive name for the patch, used as the filename in
debian/patches. Then, for every file that will be modified by this patch,
run:
quilt add <file>
before editing those files. You must tell quilt with quilt add what files
will be part of the patch before making changes or quilt will not work
properly. After editing the files, run:
quilt refresh
to save the results as a patch.
Alternately, if you already have an external patch and you just want to
add it to the build system, run quilt push -a and then:
quilt import -P <patch> /path/to/patch
quilt push -a
(add -p 0 to quilt import if needed). <patch> as above is the filename to
use in debian/patches. The last quilt push -a will apply the patch to
make sure it works properly.
To remove an existing patch from the list of patches that will be applied,
run:
quilt delete <patch>
You may need to run quilt pop -a to unapply patches first before running
this command.
---8<---
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Attachment:
pgpWr2VeWuQfw.pgp
Description: PGP signature