From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Sun, 3 Jan 2010 23:28:42 +0000 (+0000)
Subject: Update several sections to take into account the new source formats “3.0 (quilt)... 
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=f5e816ccb9b3f7134c12b82c3388b586e29c7676

Update several sections to take into account the new source formats “3.0 (quilt)” and “3.0 (native)”

* Update several sections to take into account the new source formats “3.0
  (quilt)” and “3.0 (native)”. Closes: #561952
* Drop reference to “dbs” in the section about including binary files.

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@7031 313b444b-1b9f-4f58-a734-7bb04f332e8d
---

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 77ae40d..32d5115 100644
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -96,18 +96,24 @@ diffs (e.g., from <filename>.diff.gz</filename>) and work out which patch sets
 to back out as a unit as bugs are fixed upstream.
 </para>
 <para>
-Unfortunately, the packaging system as such currently doesn't provide for
-separating the patches into several files.  Nevertheless, there are ways to
-separate patches: the patch files are shipped within the Debian patch file
-(<filename>.diff.gz</filename>), usually within the
-<filename>debian/</filename> directory.  The only difference is that they
-aren't applied immediately by dpkg-source,
-but by the <literal>build</literal>
-rule of <filename>debian/rules</filename>,
-through a dependency on the <literal>patch</literal> rule.
-Conversely, they are reverted in
-the <literal>clean</literal> rule,
-through a dependency on the <literal>unpatch</literal> rule.
+Fortunately, with the source format “3.0 (quilt)” it is now possible to
+keep patches separate without having to modify <filename>debian/rules</filename>
+to setup a patch system. Patches are stored in <filename>debian/patches/</filename>
+and when the source package is unpacked patches listed in
+<filename>debian/patches/series</filename> are automatically applied.
+As the name implies, patches can be managed with <command>quilt</command>.
+</para>
+<para>
+When using the older source “1.0”, it's also possible to separate patches
+but a dedicated patch system must be used: the patch files are shipped
+within the Debian patch file (<filename>.diff.gz</filename>), usually
+within the <filename>debian/</filename> directory. The only difference is
+that they aren't applied immediately by <command>dpkg-source</command>,
+but by the <literal>build</literal> rule of
+<filename>debian/rules</filename>, through a dependency on the
+<literal>patch</literal> rule.  Conversely, they are reverted in the
+<literal>clean</literal> rule, through a dependency on the
+<literal>unpatch</literal> rule.
 </para>
 <para>
 <command>quilt</command> is the recommended tool for this.
@@ -1661,7 +1667,7 @@ upstream source.
 <title>Pristine source</title>
 <para>
 The defining characteristic of a pristine source tarball is that the
-<literal>.orig.tar.gz</literal> file is byte-for-byte identical to a tarball officially
+<literal>.orig.tar.{gz,bz2}</literal> file is byte-for-byte identical to a tarball officially
 distributed by the upstream author.  <footnote><para> We cannot prevent
 upstream authors from changing the tarball they distribute without also
 incrementing the version number, so there can be no guarantee that a pristine
@@ -1671,7 +1677,7 @@ identical to something that upstream once <emphasis>did</emphasis> distribute.
 If a difference arises later (say, if upstream notices that he wasn't using
 maximal compression in his original distribution and then
 re-<command>gzip</command>s it), that's just too bad.  Since there is no good
-way to upload a new <literal>.orig.tar.gz</literal> for the same version, there is not even any
+way to upload a new <literal>.orig.tar.{gz,bz2}</literal> for the same version, there is not even any
 point in treating this situation as a bug.  </para> </footnote> This makes it
 possible to use checksums to easily verify that all changes between Debian's
 version and upstream's are contained in the Debian diff.  Also, if the original
@@ -1725,11 +1731,11 @@ gzipped tar at all, or if upstream's tarball contains non-DFSG-free material
 that you must remove before uploading.
 </para>
 <para>
-In these cases the developer must construct a suitable <literal>.orig.tar.gz
+In these cases the developer must construct a suitable <literal>.orig.tar.{gz,bz2}
 </literal> file himself.  We refer to such a tarball as a repackaged upstream 
 source.  Note that a repackaged upstream source is different from a 
 Debian-native package.  A repackaged source still comes with Debian-specific
-changes in a separate <literal>.diff.gz</literal> and still has a version
+changes in a separate <literal>.diff.gz</literal> or <literal>.debian.tar.{gz,bz2}</literal> and still has a version
 number composed of <literal>&lt;upstream-version&gt;</literal> and
 <literal>&lt;debian-revision&gt;</literal>.
 </para>
@@ -1743,7 +1749,7 @@ archive.  Use your own discretion here, but be prepared to defend your decision
 if you repackage source that could have been pristine.
 </para>
 <para>
-A repackaged <literal>.orig.tar.gz</literal>
+A repackaged <literal>.orig.tar.{gz,bz2}</literal>
 </para>
 <orderedlist numeration="arabic">
 <listitem>
@@ -1798,47 +1804,24 @@ distinguish pristine tarballs from repackaged ones.
 </listitem>
 <listitem>
 <para>
-<emphasis role="strong">should</emphasis> be gzipped with maximal compression.
+<emphasis role="strong">should</emphasis> be gzipped or bzipped with maximal compression.
 </para>
 </listitem>
 </orderedlist>
-<para>
-The canonical way to meet the latter two points is to let <literal>dpkg-source
--b</literal> construct the repackaged tarball from an unpacked directory.
-</para>
 </section>
 
 <section id="changed-binfiles">
-<title>Changing binary files in <literal>diff.gz</literal></title>
+<title>Changing binary files</title>
 <para>
 Sometimes it is necessary to change binary files contained in the original
-tarball, or to add binary files that are not in it.  If this is done by simply
-copying the files into the debianized source tree,
-<command>dpkg-source</command> will not be able to handle this.  On the other
-hand, according to the guidelines given above, you cannot include such a
-changed binary file in a repackaged <filename>orig.tar.gz</filename>.  Instead,
-include the file in the <filename>debian</filename> directory in
-<command>uuencode</command>d (or similar) form <footnote><para> The file should
-have a name that makes it clear which binary file it encodes.  Usually, some
-postfix indicating the encoding should be appended to the original filename.
-Note that you don't need to depend on <systemitem
-role="package">sharutils</systemitem> to get the <command>uudecode</command>
-program if you use <command>perl</command>'s <literal>pack</literal> function.
-The code could look like
-</para>
-&example-uu;
-</footnote>.  The file would then be
-decoded and copied to its place during the build process.  Thus the change will
-be visible quite easy.
-</para>
-<para>
-Some packages use <command>dbs</command> to manage patches to their upstream
-source, and always create a new <literal>orig.tar.gz</literal> file that
-contains the real <literal>orig.tar.gz</literal> in its toplevel directory.
-This is questionable with respect to the preference for pristine source.  On
-the other hand, it is easy to modify or add binary files in this case: Just put
-them into the newly created <literal>orig.tar.gz</literal> file, besides the
-real one, and copy them to the right place during the build process.
+tarball, or to add binary files that are not in it. This is fully supported
+when using source packages in “3.0 (quilt)” format, see the
+<citerefentry><refentrytitle>dpkg-source</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+manual page for details. When using the older format “1.0”, binary files
+can't be stored in the <filename>.diff.gz</filename> so you must store
+an <command>uuencode</command>d (or similar) version of the file(s)
+and decode it at build time in <filename>debian/rules</filename> (and move
+it in its official location).
 </para>
 </section>
 
diff --git a/debian/changelog b/debian/changelog
index d9c172f..6066808 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -26,6 +26,9 @@ developers-reference (3.4.4) UNRELEASED; urgency=low
   * Mention docbook, POD and reST as convenient formats to write new manual
     pages. Thanks to Charles Plessy and the debian-mentors list
     for the idea and the patch. Closes: #557298
+  * Update several sections to take into account the new source formats “3.0
+    (quilt)” and “3.0 (native)”. Closes: #561952
+  * Drop reference to “dbs” in the section about including binary files.
 
  -- Lucas Nussbaum <lucas@lucas-nussbaum.net>  Tue, 22 Dec 2009 22:49:40 +0900
 
diff --git a/pkgs.dbk b/pkgs.dbk
index 3dc249e..8dd84be 100644
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -223,23 +223,25 @@ distinction between the original sources and the patches applied for Debian
 <listitem>
 <para>
 the (more common) packages where there's an original source tarball file
-accompanied by another file that contains the patches applied for Debian
+accompanied by another file that contains the changes made by Debian
 </para>
 </listitem>
 </itemizedlist>
 <para>
 For the native packages, the source package includes a Debian source control
 file (<literal>.dsc</literal>) and the source tarball
-(<literal>.tar.gz</literal>).  A source package of a non-native package
+(<literal>.tar.{gz,bz2,lzma}</literal>). A source package of a non-native package
 includes a Debian source control file, the original source tarball
-(<literal>.orig.tar.gz</literal>) and the Debian patches
-(<literal>.diff.gz</literal>).
+(<literal>.orig.tar.{gz,bz2,lzma}</literal>) and the Debian changes
+(<literal>.diff.gz</literal> for the source format “1.0” or
+<literal>.debian.tar.{gz,bz2,lzma}</literal> for the source format “3.0 (quilt)”).
 </para>
 <para>
-Whether a package is native or not is determined when it is built by
-<citerefentry> <refentrytitle>dpkg-buildpackage</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>.  The rest of this section relates
-only to non-native packages.
+With source format “1.0”, whether a package is native or not was determined
+by <command>dpkg-source</command> at build time. Nowadays it is recommended
+to be explicit about the desired source format by putting either “3.0 (quilt)”
+or “3.0 (native)” in <filename>debian/source/format</filename>.
+The rest of this section relates only to non-native packages.
 </para>
 <para>
 The first time a version is uploaded which corresponds to a particular upstream
@@ -251,8 +253,8 @@ will not need to be re-uploaded.
 <para>
 By default, <command>dpkg-genchanges</command> and
 <command>dpkg-buildpackage</command> will include the original source tar file
-if and only if the Debian revision part of the source version number is 0 or 1,
-indicating a new upstream version.  This behavior may be modified by using
+if and only if the current changelog entry has a different upstream version
+from the preceding entry. This behavior may be modified by using
 <literal>-sa</literal> to always include it or <literal>-sd</literal> to always
 leave it out.
 </para>
@@ -265,8 +267,10 @@ the archive.
 </para>
 <para>
 Please notice that, in non-native packages, permissions on files that are not
-present in the .orig.tar.gz will not be preserved, as diff does not store file
-permissions in the patch.
+present in the .orig.tar.{gz,bz2} will not be preserved, as diff does not store file
+permissions in the patch. However when using source format “3.0 (quilt)”,
+permissions of files inside the <filename>debian</filename> directory are
+preserved since they are stored in a tar archive.
 </para>
 </section>
 
@@ -1158,7 +1162,7 @@ upload without upstream source (<literal> dpkg-buildpackage -sd</literal>).
 <listitem>
 <para>
 Be sure to use the <emphasis role="strong">exact same
-<filename>*.orig.tar.gz</filename></emphasis> as used in the
+<filename>*.orig.tar.{gz,bz2}</filename></emphasis> as used in the
 normal archive, otherwise it is not possible to move the security fix into the
 main archives later.
 </para>
@@ -1244,7 +1248,7 @@ control information to place the package in the desired section, and re-upload
 the package (see the <ulink
 url="&url-debian-policy;">Debian Policy Manual</ulink> for
 details).  You must ensure that you include the
-<filename>.orig.tar.gz</filename> in your upload (even if you are not uploading
+<filename>.orig.tar.{gz,bz2}</filename> in your upload (even if you are not uploading
 a new upstream version), or it will not appear in the new section together with
 the rest of the package.  If your new section is valid, it will be moved
 automatically.  If it does not, then contact the ftpmasters in order to
@@ -1393,9 +1397,10 @@ Note that this applies to each part of your package, including the sources: if
 you wish to replace the upstream source tarball of your package, you will need
 to upload it with a different version.  An easy possibility is to replace
 <filename>foo_1.00.orig.tar.gz</filename> with
-<filename>foo_1.00+0.orig.tar.gz</filename>.  This restriction gives each file
-on the ftp site a unique name, which helps to ensure consistency across the
-mirror network.
+<filename>foo_1.00+0.orig.tar.gz</filename> or
+<filename>foo_1.00.orig.tar.bz2</filename>.  This restriction gives each
+file on the ftp site a unique name, which helps to ensure consistency
+across the mirror network.
 </para>
 </section>
 
diff --git a/resources.dbk b/resources.dbk
index 936bef2..1ff6c94 100644
--- a/resources.dbk
+++ b/resources.dbk
@@ -571,20 +571,33 @@ There are two types of Debian packages, namely <literal>source</literal> and
 <literal>binary</literal> packages.
 </para>
 <para>
-Source packages consist of either two or three files: a
-<filename>.dsc</filename> file, and either a <filename>.tar.gz</filename> file
-or both an <filename>.orig.tar.gz</filename> and a
-<filename>.diff.gz</filename> file.
-</para>
-<para>
-If a package is developed specially for Debian and is not distributed outside
-of Debian, there is just one <filename>.tar.gz</filename> file which contains
-the sources of the program.  If a package is distributed elsewhere too, the
-<filename>.orig.tar.gz</filename> file stores the so-called <literal>upstream
-source code</literal>, that is the source code that's distributed by the
-<literal>upstream maintainer</literal> (often the author of the software).
-In this case, the <filename>.diff.gz</filename> contains the changes made by
-the Debian maintainer.
+Depending on the format of the source package, it will consist
+of one or more files in addition to the mandatory <filename>.dsc</filename>
+file:
+<itemizedlist>
+<listitem><para>with format “1.0”, it has either a <filename>.tar.gz</filename>
+file or both an <filename>.orig.tar.gz</filename> and a
+<filename>.diff.gz</filename> file;</para></listitem>
+<listitem><para>with format “3.0 (quilt)”, it has a mandatory
+<filename>.orig.tar.{gz,bz2,lzma}</filename> upstream tarball,
+muliple optional <filename>.orig-<replaceable>component</replaceable>.tar.{gz,bz2,lzma}</filename> additional upstream tarballs</para> and a
+mandatory <filename>debian.tar.{gz,bz2,lzma} debian tarball</filename>;</listitem>
+<listitem><para>with format “3.0 (native)”, it has only
+a single <filename>.tar.{gz,bz2,lzma}</filename> tarball.</para></listitem>
+</itemizedlist>
+</para>
+<para>
+If a package is developed specially for Debian and is not distributed
+outside of Debian, there is just one
+<filename>.tar.{gz,bz2,lzma}</filename> file which contains the sources of
+the program, it's called a “native” source package.  If a package is
+distributed elsewhere too, the
+<filename>.orig.tar.{gz,bz2,lzma}</filename> file stores the so-called
+<literal>upstream source code</literal>, that is the source code that's
+distributed by the <literal>upstream maintainer</literal> (often the
+author of the software). In this case, the <filename>.diff.gz</filename>
+or the <filename>debian.tar.{gz,bz2,lzma}</filename> contains the changes
+made by the Debian maintainer.
 </para>
 <para>
 The <filename>.dsc</filename> file lists all the files in the source package