Okay, here is a new and hopefully final version of the README.source
patch. If you have any other comments or concerns, please speak up now;
otherwise, I will apply this patch for the next Policy release.
--- orig/policy.sgml
+++ mod/policy.sgml
@@ -1926,6 +1926,19 @@
possible is a good idea.
</p>
</item>
+
+ <tag><tt>patch</tt> (optional)</tag>
+ <item>
+ <p>
+ This target performs whatever additional actions are
+ required to make the source ready for editing (unpacking
+ additional upstream archives, applying patches, etc.).
+ It is recommended to be implemented for any package where
+ <tt>dpkg-source -x</tt> does not result in source ready
+ for additional modification. See
+ <ref id="readmesource">.
+ </p>
+ </item>
</taglist>
<p>
@@ -2076,6 +2089,57 @@
the file to the list in <file>debian/files</file>.</p>
</sect>
+ <sect>
+ <heading>Source package handling:
+ <file>debian/README.source</file></heading>
+
+ <p>
+ If running <prgn>dpkg-source -x</prgn> on a source package
+ doesn't produce the source of the package, ready for editing,
+ and allow one to make changes and run
+ <prng>dpkg-buildpackage</prgn> to produce a modified package
+ without taking any additional steps, creating a
+ <file>debian/README.source</file> documentation file is
+ recommended. This file should explain how to do all of the
+ following:
+ <enumlist>
+ <item>Generate the fully patched source, in a form ready for
+ editing, that would be built to create Debian
+ packages. Doing this with a <tt>patch</tt> target in
+ <file>debian/rules</file> is recommended; see
+ <ref id="debianrules">.</item>
+ <item>Modify the source and save those modifications so that
+ they will be applied when building the package.</item>
+ <item>Remove source modifications that are currently being
+ applied when building the package.</item>
+ <item>Optionally, document what steps are necessary to
+ upgrade the Debian source package to a new upstream version,
+ if applicable.</item>
+ </enumlist>
+ 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ <file>debian/README.source</file> 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
+ <file>debian/README.source</file> 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).
+ </p>
+ </sect>
</chapt>
--
Russ Allbery ([EMAIL PROTECTED]) <http://www.eyrie.org/~eagle/>
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
