X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=developers-reference.sgml;h=5ff3f5190397534ec79c564bae7ce161b627ec1e;hb=41145695d172cd34975aba3921b411daf1a4a6f7;hp=2d1b11dd48c6bdd80b20a04ffb80f4ea9723b7c2;hpb=07af0a0f61dd357a1c0636072c5b9a84591be26d;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 2d1b11d..5ff3f51 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.171 $">
+  <!entity cvs-rev "$Revision: 1.177 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -514,7 +514,7 @@ all the files.
 There are other additional channels dedicated to specific subjects.
 <em>#debian-bugs</em> is used for coordinating bug squash parties.
 <em>#debian-boot</em> is used to coordinate the work on the boot
-floppies (i.e. the installer). <em>#debian-doc</em> is
+floppies (i.e., the installer). <em>#debian-doc</em> is
 occasionally used to talk about documentation, like the document you are
 reading. Other channels are dedicated to an architecture or a set of
 packages: <em>#debian-bsd</em>, <em>#debian-kde</em>, <em>#debian-jr</em>,
@@ -1430,7 +1430,7 @@ packages.
 	  <p>
 The <file>debian/changelog</file> file conforms to a certain structure,
 with a number of different fields.  One field of note, the
-<em>distribution</em>, is described in <ref id="upload-dist">.  More
+<em>distribution</em>, is described in <ref id="distribution">.  More
 information about the structure of this file can be found in
 the Debian Policy section titled "<file>debian/changelog</file>".
 	  <p>
@@ -1451,16 +1451,8 @@ and <ref id="dpkg-dev-el">.
 See also <ref id="bpp-debian-changelog">.
 
 
-    <sect id="upload">Package uploads
-
-	  <p>
-When a package is uploaded to the Debian archive, it must be accompanied by
-a <tt>.changes</tt> control file, which gives directions to the archive
-maintenance software for its handling. This is generated by
-<prgn>dpkg-genchanges</prgn> during the normal package build process.
-
-      <sect1 id="upload-checking">Checking the package prior to upload
-	  <p>
+    <sect id="sanitycheck">Testing the package
+	<p>
 Before you upload your package, you should do basic testing on it.  At
 a minimum, you should try the following activities (you'll need to
 have an older version of the same Debian package around):
@@ -1483,6 +1475,9 @@ to emit errors (they will start with <tt>E</tt>).
 		<p>
 For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
 	      <item>
+Optionally run <ref id="debdiff"> to analyze changes from an older version,
+if one exists.
+	      <item>
 Downgrade the package to the previous version (if one exists) &mdash; this
 tests the <file>postrm</file> and <file>prerm</file> scripts.
 	      <item>
@@ -1490,74 +1485,74 @@ Remove the package, then reinstall it.
 	    </list>
 
 
-      <sect1>Layout of the source files
-	  <p>
+    <sect id="sourcelayout">Layout of the source package
+	<p>
 There are two types of Debian source packages:
-	  <list>
+	<list>
 	  <item>the so-called <em>native</em> packages, where there is no
 		distinction between the original sources and the patches
 		applied for Debian
 	  <item>the (more common) packages where there's an original source
 		tarball file accompanied by another file that contains the
 		patches applied for Debian
-	  </list>
-	  <p>
+	</list>
+	<p>
 For the native packages, the source package includes a Debian source control
 file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source
 package of a non-native package includes a Debian source control file, the
 original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches
 (<tt>.diff.gz</tt>).
-	  <p>
+	<p>
 Whether a package is native or not is determined when it is built by
 <manref name="dpkg-buildpackage" section="1">. The rest of this section
 relates only to non-native packages.
-	  <p>
+	<p>
 The first time a version is uploaded which corresponds to a particular
 upstream version, the original source tar file should be uploaded and
 included in the <file>.changes</file> file.  Subsequently, this very same
 tar file should be used to build the new diffs and <file>.dsc</file>
 files, and will not need to be re-uploaded.
-	  <p>
+	<p>
 By default, <prgn>dpkg-genchanges</prgn> and
 <prgn>dpkg-buildpackage</prgn> 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 <tt>-sa</tt> to always include it or
 <tt>-sd</tt> to always leave it out.
-	  <p>
+	<p>
 If no original source is included in the upload, the original
 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
 <file>.dsc</file> file and diff to be uploaded <em>must</em> be
 byte-for-byte identical with the one already in the archive.
 
 
-      <sect1 id="upload-dist">Picking a distribution
-	  <p>
+    <sect id="distribution">Picking a distribution
+	<p>
 Each upload needs to specify which distribution the package is intended
 for. The package build process extracts this information from the first
 line of the <file>debian/changelog</file> file and places it in the
 <tt>Distribution</tt> field of the <tt>.changes</tt> file.
-	  <p>
+	<p>
 There are several possible values for this field: `stable', `unstable',
 `testing-proposed-updates' and `experimental'. Normally, packages are
 uploaded into <em>unstable</em>.
-	  <p>
+	<p>
 Actually, there are two other possible distributions: `stable-security' and
 `testing-security', but read <ref id="bug-security"> for more information on
 those.
-	  <p>
+	<p>
 It is technically possible to upload a package into several distributions
 at the same time but it usually doesn't make sense to use that feature
 because the dependencies of the package may vary with the distribution.
 In particular, it never makes sense to combine the <em>experimental</em>
 distribution with anything else.
 
-	<sect2 id="upload-stable">Uploading to <em>stable</em>
-	    <p>
+	<sect1 id="upload-stable">Uploads to <em>stable</em>
+	  <p>
 Uploading to <em>stable</em> means that the package will be placed into the
 <file>stable-proposed-updates</file> directory of the Debian archive for further
 testing before it is actually included in <em>stable</em>.
-	    <p>
+	  <p>
 Extra care should be taken when uploading to <em>stable</em>. Basically, a
 package should only be uploaded to stable if one of the following happens:
 <list>
@@ -1566,13 +1561,13 @@ package should only be uploaded to stable if one of the following happens:
 	<item>the package becomes uninstallable
 	<item>a released architecture lacks the package
 </list>
-	    <p>
+	  <p>
 It is discouraged to change anything else in the package that isn't
 important, because even trivial fixes can cause bugs later on. Uploading
 new upstream versions to fix security problems is deprecated; applying the
 specific patch from the new upstream version to the old one ("back-porting"
 the patch) is the right thing to do in most cases.
-	    <p>
+	  <p>
 Packages uploaded to <em>stable</em> need to be compiled on systems running
 <em>stable</em>, so that their dependencies are limited to the libraries
 (and other packages) available in <em>stable</em>; for example, a package
@@ -1580,7 +1575,7 @@ uploaded to <em>stable</em> that depends on a library package that only
 exists in unstable will be rejected. Making changes to dependencies of other
 packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
 those other packages uninstallable, is strongly discouraged.
-	    <p>
+	  <p>
 The Release Team (which can be reached at &email-debian-release;) will
 regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if
 your package can be included in <em>stable</em>. Please be clear (and
@@ -1588,35 +1583,37 @@ verbose, if necessary) in your changelog entries for uploads to
 <em>stable</em>, because otherwise the package won't be considered for
 inclusion.
 
-	<sect2 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
-	    <p>
+	<sect1 id="upload-t-p-u">Uploads to <em>testing-proposed-updates</em>
+	  <p>
 The testing distribution is fed with packages from unstable according to the rules
 explained in <ref id="testing">. However, the release manager may stop the testing
 scripts when he wants to freeze the distribution. In that case, you may want to
 upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.
-	    <p>
+	  <p>
 Keep in mind that packages uploaded there are not automatically processed, they
 have to go through the hands of the release manager. So you'd better have a good
 reason to upload there. In order to know what a good reason is in the
 release manager's eyes, you should read the instructions that he regularly
 gives on &email-debian-devel-announce;.
-	    <p>
+	  <p>
 You should not upload to <em>testing-proposed-updates</em> when you can update your
 packages through <em>unstable</em>. If you can't (for example because you have a
 newer development version in unstable), you may use it but it is recommended to ask
 the authorization of the release manager before.
 
 
-      <sect1 id="uploading">Uploading a package
+    <sect id="upload">Uploading a package
 
-	<sect2 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
+	<sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
 	  <p>
 To upload a package, you need a personal account on
 <ftpsite>&ftp-master-host;</ftpsite>, which you should have as an
 official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
 to transfer the files, place them into &us-upload-dir;;
 if you use anonymous FTP to upload, place them into
-&upload-queue;.  Please note that you should transfer
+&upload-queue;.
+	  <p>
+Please note that you should transfer
 the changes file last.  Otherwise, your upload may be rejected because the
 archive maintenance software will parse the changes file and see that not
 all files have been uploaded.  If you don't want to bother with transferring
@@ -1644,10 +1641,12 @@ process of uploading packages into Debian.
 	  <p>
 After uploading your package, you can check how the archive
 maintenance software will process it by running <prgn>dinstall</prgn>
-on your changes file: <example>dinstall -n foo.changes</example>.
+on your changes file:
+<example>dinstall -n foo.changes</example>
+	  <p>
 Note that <prgn>dput</prgn> can do this for you automatically.
 
-	<sect2 id="upload-non-us">Uploading to <tt>non-US</tt>
+	<sect1 id="upload-non-us">Uploading to <tt>non-US</tt>
 	  <p>
 As discussed above, export controlled software should not be uploaded
 to <tt>ftp-master</tt>.  Instead, upload the package to
@@ -1691,7 +1690,7 @@ advice. Again, it is strongly recommended that U.S. citizens and
 residents consult a lawyer before doing uploads to non-US.
 
 
-	<sect2>Uploads via <tt>chiark</tt>
+	<sect1>Uploads via <tt>chiark</tt>
 	  <p>
 If you have a slow network connection to <tt>ftp-master</tt>, there are
 alternatives.  One is to upload files to <file>Incoming</file> via a
@@ -1708,7 +1707,7 @@ The program <prgn>dupload</prgn> comes with support for uploading to
 program for details.
 
 
-	<sect2>Uploads via <tt>erlangen</tt>
+	<sect1>Uploads via <tt>erlangen</tt>
 	  <p>
 Another upload queue is available in Germany: just upload the files
 via anonymous FTP to <url id="&url-upload-erlangen;">.
@@ -1739,7 +1738,7 @@ The program <prgn>dupload</prgn> comes with support for uploading to
 the program for details.
 
 
-	<sect2>Other upload queues
+	<sect1>Other upload queues
 	  <p>
 Another upload queue is available which is based in the US, and is a
 good backup when there are problems reaching <tt>ftp-master</tt>.  You can
@@ -1771,16 +1770,19 @@ checking if any bugs you meant to close didn't get triggered.
 The installation notification also includes information on what
 section the package was inserted into.  If there is a disparity, you
 will receive a separate email notifying you of that.  Read on below.
+	<p>
+Note also that if you upload via queues, the queue daemon software will
+also send you a notification by email.
 
-	<sect1 id="override-file">Determining section and priority of a package
-	  <p>
+    <sect id="override-file">Determining section and priority of a package
+	<p>
 The <file>debian/control</file> file's <tt>Section</tt> and
 <tt>Priority</tt> fields do not actually specify where the file will
 be placed in the archive, nor its priority.  In order to retain the
 overall integrity of the archive, it is the archive maintainers who
 have control over these fields.  The values in the
 <file>debian/control</file> file are actually just hints.
-	  <p>
+	<p>
 The archive maintainers keep track of the canonical sections and
 priorities for packages in the <em>override file</em>.  If there is a
 disparity between the <em>override file</em> and the package's fields
@@ -1789,14 +1791,14 @@ email noting the divergence when the package is installed into the
 archive.  You can either correct your <file>debian/control</file> file
 for your next upload, or else you may wish to make a change in the
 <em>override file</em>.
-	  <p>
+	<p>
 To alter the actual section that a package is put in, you need to
 first make sure that the <file>debian/control</file> in your package
 is accurate.  Next, send an email &email-override; or submit a bug
 against <package>ftp.debian.org</package> requesting that the section
 or priority for your package be changed from the old section or
 priority to the new one.  Be sure to explain your reasoning.
-	  <p>
+	<p>
 For more information about <em>override files</em>, see <manref
 name="dpkg-scanpackages" section="8"> and
 <url id="&url-bts-devel;#maintincorrect">.
@@ -1990,6 +1992,9 @@ anything to do with an upload of yours, do it simply by emailing an
 explanation to <email>XXX-done@bugs.debian.org</email>.
 Do <strong>not</strong> close bugs in the changelog entry of a version
 if the said version of the package doesn't have anything to do with the bug.
+	  <p>
+For general information on what to put in the changelog files, please
+refer to <ref id="bpp-debian-changelog">.
 
       <sect1 id="bug-security">Handling security-related bugs
         <p>
@@ -2140,9 +2145,9 @@ fix can break seemingly unrelated features in subtle ways.
 Review and test your changes as much as possible.  Check the
 differences from the previous version repeatedly
 (<prgn>interdiff</prgn> from the <package>patchutils</package> package
-and <prgn>debdiff</prgn> from <package>devscripts</package> are useful tools for
-this).
-
+and <prgn>debdiff</prgn> from <package>devscripts</package> are useful
+tools for this, see <ref id="debdiff">).
+<p>
 When packaging the fix, keep the following points in mind:
 
 <list>
@@ -2421,13 +2426,17 @@ Make sure that your <tt>Build-Depends</tt> and
 <tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
 are set properly.  The best way to validate this is to use the
 <package>debootstrap</package> package to create an unstable chroot
-environment.  Within that chrooted environment, install the
+environment (see <ref id="debootstrap">).
+Within that chrooted environment, install the
 <package>build-essential</package> package and any package
 dependencies mentioned in <tt>Build-Depends</tt> and/or
 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
 within that chrooted environment.  These steps can be automated
 by the use of the <prgn>pbuilder</prgn> program which is provided by
-the package of the same name.
+the package of the same name (see <ref id="pbuilder">).
+		<p>
+If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be
+of assistance (see <ref id="dpkg-depcheck">).
 		<p>
 See the <url id="&url-debian-policy;" name="Debian Policy
 Manual"> for instructions on setting build dependencies.
@@ -2725,7 +2734,7 @@ the bug. Don't forget to tag the bug with the "patch" keyword.
 Wait a few more days. If you still haven't got an answer from the
 maintainer, send him a mail announcing your intent to NMU the package.
 Prepare an NMU as described in <ref id="nmu-guidelines">, test it
-carefully on your machine (cf. <ref id="upload-checking">).
+carefully on your machine (cf. <ref id="sanitycheck">).
 Double check that your patch doesn't have any unexpected side effects.
 Make sure your patch is as small and as non-disruptive as it can be.  
 	    <item>
@@ -2856,9 +2865,8 @@ entry in the changelog file documenting the non-maintainer upload.
 	<sect2 id="nmu-build">Building source NMUs
 	  <p>
 Source NMU packages are built normally.  Pick a distribution using the
-same rules as found in <ref id="upload-dist">.  Just as described in
-<ref id="uploading">, a normal changes file, etc., will be built.  In
-fact, all the prescriptions from <ref id="upload"> apply.
+same rules as found in <ref id="distribution">, follow the other
+prescriptions in <ref id="upload">.
 	  <p>
 Make sure you do <em>not</em> change the value of the maintainer in
 the <file>debian/control</file> file.  Your name as given in the NMU entry of
@@ -3133,9 +3141,15 @@ to the user about a package before they install it.  It should provide
 all the required information to let the user decide whether to install
 the package.
 	    <p>
-For consistency and aesthetics, you should capitalize the first letter
-of the Synopsis.  Don't put a full stop (period) at the end.  The
-description itself should consist of full sentences.
+The following practices supplement the <url name="Policy on the descriptions
+of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
+	    <p>
+The synopsis line (the short description) should primarily be concise.
+You may capitalize the first letter for aesthetics. It is customary to
+make the synopsis an appositive clause (not a full sentence) in which
+case there's no need to put a full stop (period) at the end.
+	    <p>
+The long description should, however, always consist of full sentences.
 	    <p>
 Since the first user impression is based on the description, be
 careful to avoid spelling and grammar mistakes. Ensure that you
@@ -3457,8 +3471,8 @@ It's usually polite to note that the bugs were fixed by another developer.
 	<p>
 Changelogs shouldn't include general statements on life, the universe and
 everything ("Sorry this upload took me so long, but I caught the flu.").
-Exception can be made if the comment is funny ;-) Obviously, this is
-subjective, so it's likely best if kept out of technical documentation
+Exceptions can be made if the comment is funny ;-) Obviously, this is
+subjective, so it's likely best if it's kept out of technical documentation
 such as changelogs.
 
 	<sect2 id="bpp-changelog-dont-really-dont">
@@ -3772,7 +3786,7 @@ with <example>debsign -m"<var>FULLNAME</var> <var>email-addr</var>" <var>changes
 before uploading it to the incoming directory.
 	<p>
 The Maintainer field of the <file>control</file> file and the
-<file>changelog</file> should list the person who did the packaging, i.e. the
+<file>changelog</file> should list the person who did the packaging, i.e., the
 sponsoree. The sponsoree will therefore get all the BTS mail about the
 package. 
 	<p>
@@ -3881,7 +3895,7 @@ You should periodically get the newest <package>lintian</package> from
 option provides detailed explanations of what each error or warning means,
 what is its basis in Policy, and commonly how you can fix the problem.
 	<p>
-Refer to <ref id="upload-checking"> for more information on how and when
+Refer to <ref id="sanitycheck"> for more information on how and when
 to use Lintian.
 	<p>
 You can also see a summary of all problems reported by Lintian on your
@@ -3897,8 +3911,33 @@ packages at <url id="&url-lintian;">. Those reports contain the latest
 <package>lintian</package> but has a different set of checks.  Its
 written in Python rather than Perl.</p>
         </sect1>
+
+        <sect1 id="debdiff">
+          <heading><package>debdiff</package></heading>
+          <p>
+<prgn>debdiff</prgn> (from the <package>devscripts</package> package)
+compares file lists and control files of two packages. It is a simple
+regression test, as it will help you notice if the number of binary
+packages has changed since the last upload, or if something's changed
+in the control file. Of course, some of the changes it reports will be
+all right, but it can help you prevent various accidents.
+	  <p>
+You can run it over a pair of binary packages:
+<example>
+debdiff package_1-1_arch.deb package_2-1_arch.deb
+</example>
+	  <p>
+Or even a pair of changes files:
+<example>
+debdiff package_1-1_arch.changes package_2-1_arch.changes
+</example>
+	  <p>
+For more information please see <manref name="debdiff" section="1">.
+        </sect1>
+
       </sect>
 
+
       <sect id="tools-helpers">
         <heading>Helpers for <file>debian/rules</file></heading>
 	<p>
@@ -4147,6 +4186,29 @@ directory of your package.  For instance, when editing
 <file>debian/changelog</file>, there are handy functions for
 finalizing a version and listing the package's current bugs.</p>
         </sect1>
+
+        <sect1 id="dpkg-depcheck">
+          <heading><package>dpkg-depcheck</package></heading>
+          <p>
+<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package> package)
+runs a command under <prgn>strace</prgn> to determine all the packages that
+were used by the said command.
+	  <p>
+For Debian packages, this is useful when you have to compose a
+<tt>Build-Depends</tt> line for your new package: running the build
+process through <prgn>dpkg-depcheck</prgn> will provide you with a
+good first approximation of the build-dependencies. For example:
+<example>
+dpkg-depcheck -b debian/rules build
+</example>
+	  <p>
+<prgn>dpkg-depcheck</prgn> can also be used to check for run-time
+dependencies, especially if your package uses exec(2) to run other
+programs.
+	  <p>
+For more information please see <manref name="dpkg-depcheck" section="1">.
+        </sect1>
+
       </sect>