X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=2ba3c0c7c37ab85428c0e26fc64dfb00ea0cd4f7;hp=5ba52bf0c4a46c7e3d96200509477c7d89acd364;hb=0c1a32b72e934f36cc741c58764d9935e0a11fd6;hpb=6891820b726709c3993d982665368bb6b5919def

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 5ba52bf..2ba3c0c 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -1,9 +1,9 @@
-<!doctype debiandoc system [
-<!-- include version information so we don't have to hard code it
-     within the document -->
-<!entity % versiondata SYSTEM "version.ent"> %versiondata;
-<!entity number-of-pkgs "2250">
-<!entity number-of-maintainers "400">
+<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
+  <!-- include version information so we don't have to hard code it
+       within the document -->
+  <!entity % versiondata SYSTEM "version.ent"> %versiondata;
+  <!entity number-of-pkgs "2250">
+  <!entity number-of-maintainers "400">
 ]>
 <debiandoc>
 <!--
@@ -66,7 +66,7 @@ The resources discussed in this reference include the mailing lists
 and servers (<ref id="servers">); a discussion of the structure of the
 Debian archive (<ref id="archive">); explanation of the different
 servers which accept package uploads (<ref id="upload-master">); and a
-discussion of resources which an help maintainers with the quality of
+discussion of resources which can help maintainers with the quality of
 their packages (<ref id="tools">).
       <p>
 It should be clear that this reference does not discuss the technical
@@ -254,7 +254,7 @@ help.
 
     <chapt id="user-maint">Maintaining Your Debian Information
 
-      <sect>Maintaining Your Public Key
+      <sect id="key-maint">Maintaining Your Public Key
 	<p>
 Be very careful with your private keys.  Do not place them on any
 public servers.  Back them up.  Read the documentation that comes with
@@ -263,8 +263,12 @@ measure.
 	<p>
 If you add or remove signatures from your public key, or add or remove
 user identities, you need to update the key servers and mail your
-public key to <email>keyring-maint@debian.org</email>.  The same key
-extraction routines from <ref id="registering"> apply.
+public key to <email>keyring-maint@debian.org</email>.
+The same key extraction routines discussed in <ref id="registering">
+apply.
+	<p>
+You can find a more in-depth discussion of Debian key maintenance in
+the documentation for the <package>debian-keyring</package> package.
 
       <sect>Retiring Gracefully
 	<p>
@@ -282,7 +286,11 @@ to <email>keyring-maint@debian.org</email>.
 	  </enumlist>
 
 
-    <chapt id="servers">Mailing Lists and Servers
+    <chapt id="servers">Mailing Lists, Servers, and Other Machines
+      <p>
+In this chapter you will find a very brief road map of the Debian
+mailing lists, the main Debian servers, and other Debian machines
+which may be available to you as a developer.
 
       <sect id="mailing-lists">Mailing lists
 	<p>
@@ -327,8 +335,22 @@ posting messages.
 Online archives of mailing lists are available at <url
 id="http://www.debian.org/Lists-Archives/">.
 
+      <sect id="server-machines">Debian servers
+	<p>
+Debian servers are well known servers which serve critical functions
+in the Debian project.  Every developer should know what these servers
+are and what they do.
+	<p>
+If you have a problem with the operation of Debian server, and you
+think that the system operators need to be notified of this problem,
+please find the contact address for the particular role at <url
+id="http://www.debian.org/devel/maintainer_contacts">.  If you have a
+non-operating problems (such as packages to be remove, suggestions for
+the web site, etc.), generally you'll report a bug against a
+``pseudo-package''.  See <ref id="submit-bug"> for information on how
+to submit bugs.
 
-      <sect id="servers-master">The master server
+      <sect1 id="servers-master">The master server
 	<p>
 The master server, <tt/master.debian.org/, holds the canonical copy
 of the Debian archive (excluding the non-U.S. packages). Generally,
@@ -348,12 +370,13 @@ clear.
 	<p>
 If you find a problem with <tt/master.debian.org/ such as disk full,
 suspicious activity, or whatever, send an email to
-<email>debian-admin@debian.org</email>.
+<email>debian-admin@debian.org</email>.  Problems with the Debian FTP
+archive generally need to be reported as bugs against the
+<package>ftp.debian.org</package> pseudo-package or an email to
+<email>ftpmaster@debian.org</email>, but also see the procedures in
+<ref id="archive-manip">.
 
-      <sect id="servers-ftp">The FTP servers
-	<p>
-
-      <sect id="servers-www">The WWW servers
+      <sect1 id="servers-www">The WWW servers
 	<p>
 The main web server, <tt/www.debian.org/, is also known as
 <tt/va.debian.org/.  All developers are given accounts on this
@@ -379,21 +402,27 @@ else has already reported the problem on the <url
 id="http://www.debian.org/Bugs/db/pa/lwww.debian.org.html" name="Bug
 Tracking System">.
 
-      <sect id="servers-cvs">The CVS server
+
+      <sect1 id="servers-cvs">The CVS server
 	<p>
 <tt/cvs.debian.org/ is also known as <tt/va.debian.org/, discussed
 above.  If you need the use of a publically accessible CVS server, for
 instance, to help coordinate work on a package between many different
-developers, you can request a CVS area on the server.  Generally,
-<tt/cvs.debian.org/ offers a combination of local CVS access,
-anonymous client-server read-only access, and full client-server
-access through <prgn>ssh</prgn>.
+developers, you can request a CVS area on the server.
+	  <p>
+Generally, <tt/cvs.debian.org/ offers a combination of local CVS
+access, anonymous client-server read-only access, and full
+client-server access through <prgn>ssh</prgn>.  Also, the CVS area can
+be accessed read-only via the Web at <url
+id="http://cvs.debian.org/cgi-bin/cvsweb">.
 	<p>
 To request a CVS area, send a request via email to
-<email>debian-admin@debian.org</email>.
+<email>debian-admin@debian.org</email>.  Include the name of the
+requested CVS area, what <tt>va.debian.org</tt> user account should
+own the CVSROOT, and why you need it.
 
 
-      <sect id="servers-mirrors">Mirrors of Debian servers
+      <sect1 id="servers-mirrors">Mirrors of Debian servers
 	<p>
 The web and FTP servers have several mirrors available.  Please do not
 put heavy load on the canonical FTP or web servers.  Ideally, the
@@ -419,6 +448,70 @@ Please do not mirror off of <tt/master.debian.org/.  This host already
 has too much load.  Check the sites above for information, or email
 <email/debian-devel@lists.debian.org/.
 
+
+      <sect id="other-machines">Other Debian Machines
+	<p>
+There are other Debian machines which may be made available to you.
+You can use these for Debian-related purposes as you see fit.  Please
+be kind to system administrators, and do not use up tons and tons of
+disk space, network bandwidth, or CPU without first getting the
+approval of the local maintainers.  Usually these machines are run by
+volunteers.  Generally, these machines are for porting activities.
+	<p>
+Aside from the servers mentioned in <ref id="server-machines">, the
+following machines are, or may be made, available to you.  If an email
+address is listed, generally that person is the party to contact about
+issues on the machine.  Otherwise, the machine is probably managed by
+<email>debian-admin@debian.org</email>.
+
+<taglist>
+	    <tag><tt>faure.debian.org</tt></tag>
+	    <item>
+An Alpha; if you have an account on <tt>master</tt>, you probably
+already have an account here.
+
+	    <tag><tt>kubrick.debian.org</tt></tag>
+	    <item>
+A SPARC; if you have an account on <tt>master</tt>, you probably
+already have an account here.
+
+	    <tag><tt>pandora.debian.org</tt></tag>
+	    <item>
+An i386; if you have an account on <tt>master</tt>, you probably
+already have an account here.
+
+	    <tag><tt>albert.debian.org</tt></tag>
+	    <item>
+An Alpha; you probably want to use <tt>faure</tt> instead, but you may
+request an account from <email>debian-admin@debian.org</email>.
+
+	    <tag><tt>powerpc.debian.org</tt></tag>
+	    <item>
+A PowerPC; also known as <tt>tervola.infodrom.north.de</tt>. You may
+request an account from <email>joey@debian.org</email> or
+<email>koptein@debian.org</email>.
+
+	    <tag><tt>m68k.debian.org</tt></tag>
+	    <item>
+A Motorola 6800x0 machine; you may request an account from
+<email>joey@debian.org</email> or <email>james@nocrew.org</email>.
+Runs an autobuilder.
+
+	    <tag><tt>alpha.debian.nl</tt></tag>
+	    <item>
+An Alpha; you may request an account from
+<email>debian@cistron.nl</email>.
+
+	    <tag><tt>xia0[123].kachinatech.com</tt></tag>
+	    <item>
+SPARC and UltraSPARC machines.  <tt>xia0[12]</tt> are used for
+automatic compilation; you can request an account on xia03 (an
+UltraSPARC) from <email>wdeng@kachinatech.com</email>.
+
+	  </taglist>
+
+
+
     <chapt id="archive">The Debian Archive
 
       <sect>Overview
@@ -539,14 +632,14 @@ more and more popular, the kernel was ported to other architectures,
 too.
 	<p>
 The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola
-680x0 machines (like Atari, Amiga and Macintoshes), MIPS, and PowerPC.
-Newer kernels support more architectures, including ARM, UltraSPARC,
-and MIPS.  Since Linux supports these platforms, Debian decided that
-it should, too.  Therefore, Debian has ports underway.  In fact, we
-also have ports underway to non-Linux kernel.  Aside from
+680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC.
+The Linux 2.2 kernel supports even more architectures, including ARM
+and UltraSPARC.  Since Linux supports these platforms, Debian decided
+that it should, too.  Therefore, Debian has ports underway.  In fact,
+we also have ports underway to non-Linux kernel.  Aside from
 <em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
 <em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
-and <em>arm</em> as of this writing.
+and <em>arm</em>, as of this writing.
 
 	<p>
 Debian GNU/Linux 1.3 is only available as <em>i386</em>.  Debian 2.0
@@ -564,7 +657,6 @@ excepting perhaps the `base' subsection.  Subsections exist simply
 to simplify the organization and browsing of available packages.
 Please check the current Debian distribution to see which sections are
 available.
-<p>
 
 
       <sect>Packages
@@ -682,10 +774,22 @@ could do grave damage to a system, it might be better to put it into
 <em/experimental/.
 	  <p>
 For instance, an experimental encrypted file system should probably go
-into experimental.  A new, beta, version of some software which uses
-completely different configuration might go into experimental at the
-maintainer's discretion.  New software which isn't likely to damage
-your system can go into <em/unstable/.
+into <em>experimental</em>.  A new, beta, version of some software
+which uses completely different configuration might go into
+<em>experimental</em> at the maintainer's discretion.  New software
+which isn't likely to damage your system can go into
+<em>unstable</em>.  If you are working on an incompatible or complex
+upgrade situation, you can also use <em>experimental</em> as a staging
+area, so that testers can get early access.
+	  <p>
+However, using <em>experimental</em> as a personal staging area is not
+always the best idea.  You can't replace or upgrade the files in there
+on your own (<prgn>dinstall</prgn> and the Debian archive maintainers
+do that).  Additionally, you'll have to remember to ask the archive
+maintainers to delete the package one you have uploaded it to
+<em>unstable</em>.  Using your personal web space on
+<tt>va.debian.org</tt> is generally a better idea, so that you put
+less strain on the Debian archive maintainers.
 
 
       <sect id="codenames">Release code names
@@ -942,7 +1046,7 @@ section="5"> for more information.
 	  <p>
 If you have a slow network connection to <tt/master/, there are
 alternatives.  One is to upload files to <tt/Incoming/ via a
-cron-driven upload queue in Europe on <tt/chiark/. For details connect
+upload queue in Europe on <tt/chiark/. For details connect
 to <ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP
 and read
 <ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
@@ -958,7 +1062,7 @@ to the documentation that comes with the program for details.
 
 	<sect1>Uploads via <tt/erlangen/
 	  <p>
-Another cron-driven upload queue is available in Germany: just upload
+Another upload queue is available in Germany: just upload
 the files via anonymous FTP to <url
 id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">.
 	  <p>
@@ -1320,7 +1424,7 @@ Porting is the act of building Debian packages for architectures which
 is different from the original architecture of the package
 maintainer's binary package.  It is a unique and essential activity.
 In fact, porters do most of the actual compiling of Debian packages.
-For instance, for one <em>x86</em> binary package, there has to be a
+For instance, for one <em>i386</em> binary package, there has to be a
 recompile for each architecture, which is around five more builds.
 
 
@@ -1348,7 +1452,7 @@ Don't set architecture to a value other than ``all'' or ``any'' unless
 you really mean it.  In too many cases, maintainers don't follow the
 instructions in the <url
 id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
-name="Debian Packaging Manual">.  Setting your architecture to ``x86''
+name="Debian Packaging Manual">.  Setting your architecture to ``i386''
 is usually incorrect.
 	    <item>
 Make sure your source package is correct.  Do <tt>dpkg-source -x
@@ -1356,7 +1460,7 @@ Make sure your source package is correct.  Do <tt>dpkg-source -x
 properly.  Then, in there, try building your package from scratch with
 <tt>dpkg-buildpackage</tt>.
 	    <item>
-Make sure you don't ship your binary package with the
+Make sure you don't ship your source package with the
 <file>debian/files</file> or <file>debian/substvars</file> files.
 They should be removed by the `clean' target of
 <file>debian/rules</file>.
@@ -1372,6 +1476,12 @@ sub-case of the above issue).
 	    <item>
 Don't rely on <prgn>egcc</prgn> being available; don't rely on
 <prgn>gcc</prgn> being a certain version.
+	    <item>
+Make sure your debian/rules contains separate ``binary-arch'' and
+``binary-indep'' targets, as the Debian Packaging Manual requires.
+Make sure that both targets work independently, that is, that you can
+call the target without having called the other before. To test this,
+try to run <tt>dpkg-buildpackage -b</tt>.
 	  </enumlist>
 
 
@@ -1459,10 +1569,6 @@ architecture <var/X/.
 	<sect1 id="buildd">
 	  <heading><package>buildd</package>
 	  <p>
-<package/buildd/ is not yet available!  However, it collects a number
-of as yet unpackaged components which are currently in production
-(such as <prgn/debbuild/ and <prgn/wanna-build/.
-	  <p>
 The <package/buildd/ system is used as a distributed, client-server
 build distribution system.  It is usually used in conjunction with
 <em/auto-builders/, which are ``slave'' hosts which simply check out
@@ -1471,6 +1577,12 @@ also an email interface to the system, which allows porters to ``check
 out'' a source package (usually one which cannot yet be autobuilt) and
 work on it.
 	  <p>
+<package/buildd/ is not yet available as a package; however, most
+porting efforts are either using it currently or planning to use it in
+the near future.  It collects a number of as yet unpackaged components
+which are currently very useful and in use continually, such as
+<prgn/sbuild/ and <prgn/wanna-build/.
+	  <p>
 We are very excited about this system, since it potentially has so
 many uses.  Independent development groups can use the system for
 different sub-flavors of Debian, which may or may not really be of
@@ -1624,7 +1736,7 @@ outlining all the open bugs against your packages:
 Replace <var>maintainer-address</var> with you official Debian
 maintainer address.
 
-      <sect>Submitting Bugs
+      <sect id="submit-bug">Submitting Bugs
 	<p>
 Often as a package maintainer, you find bugs in other packages or else
 have bugs reported to your packages which need to be reassigned.  The
@@ -1804,9 +1916,6 @@ you to build packages without being root (packages usually want to
 install files with root ownership).  If you have
 <package>fakeroot</package> installed, you can say, i.e.,
 <tt>dpkg-buildpackage -rfakeroot</tt> as a user.
-	<p>
-Note that <package>fakeroot</package> is being replaced by
-<package>libtool</package> in ``potato''.
 
 
       <sect id="devscripts">
@@ -1819,7 +1928,14 @@ manipulate your <file>debian/changelog</file> file from the
 command-line, and <prgn>build</prgn>, which is a wrapper around
 <prgn>dpkg-buildpackage</prgn>.
 
-<!-- dpkg-awk ? -->
+
+      <sect id="debget">
+	<heading><package>debget</package>
+	<p>
+<package>debget</package> is a package containing a convenient script
+which can be helpful in downloading files from the Debian archive.
+You can use it to download source packages, for instance.
+
 
   </book>
 </debiandoc>