chiark / gitweb /
~ianmdlvl / developers-reference.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
* Sec. "The master server": note that problems on Debian ftp can be sent
[developers-reference.git] / developers-reference.sgml
diff --git a/developers-reference.sgml b/developers-reference.sgml
index cd8bbf972a85f762f0e0d1bef0eefa5f82b1b859..2ba3c0c7c37ab85428c0e26fc64dfb00ea0cd4f7 100644 (file)
--- 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>
 <!--
 ]>
 <debiandoc>
 <!--
@@ -263,8 +263,7 @@ 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
        <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>pgp-update@debian.org</email> or
-<email>gpg-update@debian.org</email> (depending on your type of key).
+public key to <email>keyring-maint@debian.org</email>.
 The same key extraction routines discussed in <ref id="registering">
 apply.
        <p>
 The same key extraction routines discussed in <ref id="registering">
 apply.
        <p>
@@ -287,7 +286,11 @@ to <email>keyring-maint@debian.org</email>.
          </enumlist>
 
 
          </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>
 
       <sect id="mailing-lists">Mailing lists
        <p>
@@ -332,8 +335,22 @@ posting messages.
 Online archives of mailing lists are available at <url
 id="http://www.debian.org/Lists-Archives/">.
 
 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,
        <p>
 The master server, <tt/master.debian.org/, holds the canonical copy
 of the Debian archive (excluding the non-U.S. packages). Generally,
@@ -353,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
        <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>.
-
-      <sect id="servers-ftp">The FTP servers
-       <p>
+<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-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
        <p>
 The main web server, <tt/www.debian.org/, is also known as
 <tt/va.debian.org/.  All developers are given accounts on this
@@ -384,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">.
 
 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
        <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
        <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
        <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
@@ -424,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/.
 
 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
     <chapt id="archive">The Debian Archive
 
       <sect>Overview
@@ -544,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
 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>,
 <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
 
        <p>
 Debian GNU/Linux 1.3 is only available as <em>i386</em>.  Debian 2.0
@@ -569,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.
 to simplify the organization and browsing of available packages.
 Please check the current Debian distribution to see which sections are
 available.
-<p>
 
 
       <sect>Packages
 
 
       <sect>Packages
@@ -687,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
 <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
 
 
       <sect id="codenames">Release code names
@@ -947,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
          <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>.
 to <ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP
 and read
 <ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
@@ -963,7 +1062,7 @@ to the documentation that comes with the program for details.
 
        <sect1>Uploads via <tt/erlangen/
          <p>
 
        <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>
 the files via anonymous FTP to <url
 id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">.
          <p>
@@ -1325,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.
 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.
 
 
 recompile for each architecture, which is around five more builds.
 
 
@@ -1353,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/"
 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
 is usually incorrect.
            <item>
 Make sure your source package is correct.  Do <tt>dpkg-source -x
@@ -1361,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>
 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>.
 <file>debian/files</file> or <file>debian/substvars</file> files.
 They should be removed by the `clean' target of
 <file>debian/rules</file>.
@@ -1377,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>
 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>
 
 
          </enumlist>
 
 
@@ -1464,10 +1569,6 @@ architecture <var/X/.
        <sect1 id="buildd">
          <heading><package>buildd</package>
          <p>
        <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
 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
@@ -1476,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>
 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
 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
@@ -1629,7 +1736,7 @@ outlining all the open bugs against your packages:
 Replace <var>maintainer-address</var> with you official Debian
 maintainer address.
 
 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
        <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
@@ -1809,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.
 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>libtricks</package> in ``potato''.
 
 
       <sect id="devscripts">
 
 
       <sect id="devscripts">
Unnamed repository; edit this file 'description' to name the repository.