Add README.source and the patch target

Specifies the debian/README.source file to document any package that
uses a source or package management system or that has a complex source
layout or build system.  Specifies and recommends the patch target
for putting a source package into an editable state.  Allowed referring
to external documentation in README.source if it's specific and not a
general manual.

git-archimport-id: rra@debian.org--lenny/debian-policy--devel--3.7--patch-41

diff --git a/debian/changelog b/debian/changelog
index 1b9056356934676f7ea4480f591dd356ccbb4836..744e7b3fb16557b6c9c377d42429fde8d3b5b7d3 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,5 +1,8 @@
 debian-policy (3.7.4.0) unstable; urgency=low
 
+  * Bug fix: "[PROPOSAL] "debian/README.source" file for packages with
+    non-trivial source", thanks to Wouter Verhelst, Jörg Sommer, Colin Watson,
+    and Junichi Uekawa                                       (Closes: #250202).
   * Bug fix: "[AMENDMENT 11/02/2008] Manual page encoding", thanks to
     Colin Watson                                             (Closes: #440420).
   * Bug fix: "[PROPOSAL] common interface for parallel building in

diff --git a/policy.sgml b/policy.sgml
index 888de5aec75a60ac90b3edc1fb27e131621d405e..1ad9699bf85362d57bb259de148ceef02e94f75a 100644 (file)
--- a/policy.sgml
+++ b/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>
@@ -2203,6 +2216,57 @@ endif
        </p>
       </sect>
 
+      <sect id="readmesource">
+       <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>
 
 

diff --git a/upgrading-checklist.html b/upgrading-checklist.html
index e344403bc34fe521693c25b4cda7716ae9f46628..5b6b5c9f057621df71f8c07b0d03c31cb8a04fef 100644 (file)
--- a/upgrading-checklist.html
+++ b/upgrading-checklist.html
@@ -58,6 +58,9 @@ picking your way through this list.
      * The base section has been removed.  contrib and non-free have been
        removed from the section list; they are only categories.  The base
        system is now defined by priority.                        [2.4, 3.7]
+     * If dpkg-source -x doesn't provide the source that will be compiled,
+       a debian/rules patch target is recommended and should do whatever
+       else is necessary.                                        [4.9]
      * Standardized the format of DEB_BUILD_OPTIONS.  Specified permitted
        characters for tags, required that tags be whitespace-separated,
        allowed packages to assume non-conflicting tags, and required
@@ -68,6 +71,13 @@ picking your way through this list.
      * Debian packages should not use convience copies of code from other
        packages unless the included package is explicitly intended to be
        used that way.                                            [4.13]
+     * If dpkg-source -x doesn't produce source ready for editing and
+       building with dpkg-buildpackage, packages should include a
+       debian/README.source file explaining how to generate the patched
+       source, add a new modification, and remove an existing
+       modification.  This file may also be used to document packaging a
+       new upstream release and any other complexity of the Debian build
+       process.                                                  [4.14]
      * The Uploaders field in debian/control may be wrapped.     [5.6.3]
      * New Homepage field for upstream web sites.                [5.6.23]
      * The Breaks field declares that this package breaks another and