X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=best-pkging-practices.dbk;h=f7b5a7b19ea563d672b966fb13dd51f83fa766b1;hp=4f47a696a2cabb836b65aec3552ef1f057f114bf;hb=0a8c38a19726ed440885e418b43bcf252df8857b;hpb=ee5cd8e4b25b5cc08eba4e381cfdfe56d4d7b911

diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
index 4f47a69..f7b5a7b 100644
--- a/best-pkging-practices.dbk
+++ b/best-pkging-practices.dbk
@@ -1670,10 +1670,17 @@ your short description.  If you are looking for examples, just run:
 <command>apt-cache search .|grep dummy</command> or
 <command>apt-cache search .|grep transitional</command>.
 </para>
+<para>
+Also, it is recommended to adjust its section to
+<literal>oldlibs</literal>
+and its priority to
+<literal>extra</literal>
+in order to ease <command>deborphan</command>'s job.
+</para>
 </section>
 
 <section id="bpp-origtargz">
-<title>Best practices for <filename>.orig.tar.{gz,bz2,lzma}</filename> files</title>
+<title>Best practices for <filename>.orig.tar.{gz,bz2,xz}</filename> files</title>
 <para>
 There are two kinds of original source tarballs: Pristine source and repackaged
 upstream source.
@@ -1682,7 +1689,7 @@ upstream source.
 <title>Pristine source</title>
 <para>
 The defining characteristic of a pristine source tarball is that the
-<filename>.orig.tar.{gz,bz2,lzma}</filename> file is byte-for-byte identical to a tarball officially
+<filename>.orig.tar.{gz,bz2,xz}</filename> 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
@@ -1692,7 +1699,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 <filename>.orig.tar.{gz,bz2,lzma}</filename> for the same version, there is not even any
+way to upload a new <filename>.orig.tar.{gz,bz2,xz}</filename> 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
@@ -1746,17 +1753,17 @@ 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 <filename>.orig.tar.{gz,bz2,lzma}</filename>
+In these cases the developer must construct a suitable <filename>.orig.tar.{gz,bz2,xz}</filename>
 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 <filename>.diff.gz</filename> or <filename>.debian.tar.{gz,bz2,lzma}</filename>
+changes in a separate <filename>.diff.gz</filename> or <filename>.debian.tar.{gz,bz2,xz}</filename>
 and still has a version number composed of <replaceable>upstream-version</replaceable> and
 <replaceable>debian-version</replaceable>.
 </para>
 <para>
 There may be cases where it is desirable to repackage the source even though
-upstream distributes a <filename>.tar.{gz,bz2,lzma}</filename> that could in principle be
+upstream distributes a <filename>.tar.{gz,bz2,xz}</filename> that could in principle be
 used in its pristine form.  The most obvious is if
 <emphasis>significant</emphasis> space savings can be achieved by recompressing
 the tar archive or by removing genuinely useless cruft from the upstream
@@ -1764,7 +1771,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 <filename>.orig.tar.{gz,bz2,lzma}</filename>
+A repackaged <filename>.orig.tar.{gz,bz2,xz}</filename>
 </para>
 <orderedlist numeration="arabic">
 <listitem>
@@ -1897,6 +1904,33 @@ debugging symbols for, and this dependency should be versioned.  For example:
 Depends: libfoo (= ${binary:Version})
 </screen>
 </section>
+<section id="bpp-meta">
+<title>Best practices for meta-packages</title>
+<para>
+A meta-package is a mostly empty package that makes it easy to install a
+coherent set of packages that can evolve over time. It achieves this by
+depending on all the packages of the set. Thanks to the power of APT, the
+meta-package maintainer can adjust the dependencies and the user's system
+will automatically get the supplementary packages. The dropped packages
+that were automatically installed will be also be marked as removal
+candidates (and are even automatically removed by <command>aptitude</command>).
+<systemitem role="package">gnome</systemitem> and
+<systemitem role="package">linux-image-amd64</systemitem> are two examples
+of meta-packages (built by the source packages
+<systemitem role="package">meta-gnome2</systemitem> and
+<systemitem role="package">linux-latest</systemitem>).
+</para>
+<para>
+The long description of the meta-package must clearly document its purpose
+so that the user knows what he will lose if he removes the package. Being
+explicit about the consequences is recommended. This is particularly
+important for meta-packages which are installed during initial
+installation and that have not been explicitly installed by the user.
+Those tend to be important to ensure smooth system upgrades and
+the user should be discouraged from uninstalling them to avoid
+potential breakages.
+</para>
+</section>
 
 </section>