From 2c8adcaa4615abfb6c77322a6ce6a2300852efe0 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Sun, 16 Mar 2008 21:08:56 +0000 Subject: [PATCH] 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 --- debian/changelog | 3 ++ policy.sgml | 64 ++++++++++++++++++++++++++++++++++++++++ upgrading-checklist.html | 10 +++++++ 3 files changed, 77 insertions(+) diff --git a/debian/changelog b/debian/changelog index 1b90563..744e7b3 100644 --- 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 888de5a..1ad9699 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1926,6 +1926,19 @@ possible is a good idea.

+ + patch (optional) + +

+ 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 + dpkg-source -x does not result in source ready + for additional modification. See + . +

+

@@ -2203,6 +2216,57 @@ endif

+ + 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: + + 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 + . + Modify the source and save those modifications so that + they will be applied when building the package. + Remove source modifications that are currently being + applied when building the package. + 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). +

+ diff --git a/upgrading-checklist.html b/upgrading-checklist.html index e344403..5b6b5c9 100644 --- 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 -- 2.39.5