X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=developers-reference.sgml;h=3b1206feb930bff99b49e0076307e098b909c228;hb=af4a79e2cde3500ee7977db96bf127159508ddab;hp=58c6e9dbe882c1b11c6494bcab88f39773cbfa7a;hpb=dc8127be4b292e0a08170d665857c7da1301a9d7;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 58c6e9d..3b1206f 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.116 $">
+  <!entity cvs-rev "$Revision: 1.121 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -111,7 +111,7 @@ to &email-debian-devel-req;.  In case of problems, contact the list
 administrator at &email-listmaster;.  More information on available
 mailing lists can be found in <ref id="mailing-lists">.
 &email-debian-devel-announce; is another list which is mandatory
-for anyone who wish to follow Debian's development.
+for anyone who wishes to follow Debian's development.
 	<p>
 You should subscribe and lurk (that is, read without posting) for a
 bit before doing any coding, and you should post about your intentions
@@ -288,8 +288,8 @@ You have to keep the information available there up-to-date.
       <sect id="key-maint">Maintaining your public key
 	<p>
 Be very careful with your private keys.  Do not place them on any
-public servers or multiuser machines, such as
-<tt>&master-host;</tt>.  Back your keys up; keep a copy offline.
+public servers or multiuser machines, such as the Debian servers
+(see <ref id="server-machines">).  Back your keys up; keep a copy offline.
 Read the documentation that comes with your software; read the <url
 id="&url-pgp-faq;" name="PGP FAQ">.
 	<p>
@@ -402,35 +402,70 @@ emailing to &email-debian-keyring;.
    <chapt id="resources">Resources for Debian Developers
      <p>
 In this chapter you will find a very brief road map of the Debian
-mailing lists, the main Debian servers, other Debian machines
+mailing lists, the Debian machines
 which may be available to you as a developer, and all the other
 resources that are available to help you in your maintainer work.
 
       <sect id="mailing-lists">Mailing lists
 	<p>
-The mailing list server is at <tt>&lists-host;</tt>.  Mail
+The mailing list server is at <tt>&lists-host;</tt>.
+	<p>
+Online archives of mailing lists are available at <url
+id="&url-lists-archives;">.
+
+	<sect1 id="core-devel-mailing-lists">Core development mailing lists
+	<p>
+The core Debian mailing lists that developers should use are:
+<list>
+  <item>&email-debian-devel-announce;, used to announce important things to
+        developers.
+        All developers are expected to be subscribed to this list.
+  </item>
+  <item>&email-debian-devel;, used to discuss various development related
+        technical issues.
+  </item>
+  <item>&email-debian-policy;, where the Debian Policy is discussed and
+        voted on.
+  </item>
+  <item>&email-debian-project;, used to discuss various non-technical
+        issues related to the project.
+  </item>
+</list>
+	<p>
+There are
+other mailing lists available for a variety of special topics; see
+<url id="&url-debian-lists-subscribe;"> for a list.
+
+	<sect1 id="mailing-lists-subunsub">Subscribing and unsubscribing
+	<p>
+To subscribe to or unsubscribe from any of the Debian mailing lists, email
 <tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
 <tt>debian-<var>foo</var></tt> is the name of the list, with the word
 <tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
-<tt>unsubscribe</tt> to unsubscribe.  More detailed instructions on
-how to subscribe and unsubscribe to the mailing lists can be found at
-<url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;">
-or locally in &file-mail-lists; if you have the
-<package>doc-debian</package> package installed.
+<tt>unsubscribe</tt> to unsubscribe.
+	<p>
+If you prefer to use a web page to subscribe to multiple mailing lists,
+there's one at <url id="&url-debian-lists-subscribe;">.
+	<p>
+You can download the current list of mailing lists and basic usage
+instructions from <url id="&url-debian-lists;">
+or install the <package>doc-debian</package> package and have it
+locally in &file-mail-lists;.
+
+	<sect1 id="mailing-lists-rules">Basic rules for use
 	<p>
 When replying to messages on the mailing list, please do not send a
 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
 request to be copied.  Anyone who posts to a mailing list should read
 it to see the responses.
 	<p>
-The following are the core Debian mailing lists: &email-debian-devel;,
-&email-debian-policy;, &email-debian-user;, &email-debian-private;,
-&email-debian-announce;, and &email-debian-devel-announce;.  All
-developers are expected to be subscribed to at least
-&email-debian-devel-announce;.  There are
-other mailing lists available for a variety of special topics; see
-<url id="&url-debian-lists-subscribe;"> for a list.  Cross-posting
-(sending the same message to multiple lists) is discouraged.
+Cross-posting (sending the same message to multiple lists) is discouraged.
+As ever on the net, please trim down the quoting of articles you're
+replying to.  In general, please adhere to the usual conventions for
+posting messages. Please read the <url name="code of conduct"
+id="&url-debian-lists;"> for more information.
+
+	<sect1 id="mailing-lists-special">Special lists
 	<p>
 &email-debian-private; is a special mailing list for private
 discussions amongst Debian developers.  It is meant to be used for
@@ -439,20 +474,13 @@ As such, it is a low volume list, and users are urged not to use
 &email-debian-private; unless it is really necessary.  Moreover, do
 <em>not</em> forward email from that list to anyone.  Archives of this
 list are not available on the web for obvious reasons, but you can see
-them using your shell account on <tt>&master-host;</tt> and looking
+them using your shell account on <tt>lists.debian.org</tt> and looking
 in the <file>~debian/archive/debian-private</file> directory.
 	<p>
 &email-debian-email; is a special mailing list used as a grab-bag 
 for Debian related correspondence such as contacting upstream authors
 about licenses, bugs, etc. or discussing the project with others where it
 might be useful to have the discussion archived somewhere.
-	<p>
-As ever on the net, please trim down the quoting of articles you're
-replying to.  In general, please adhere to the usual conventions for
-posting messages.
-	<p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
 
       <sect id="irc-channels">IRC channels
 	<p>
@@ -469,7 +497,9 @@ always full of interesting information. Since it's an open channel, you
 should not speak there of issues that are discussed in
 &email-debian-private;. There's a key protected channel
 <em>#debian-private</em> for that purpose. The key is available 
-in the archives of debian-private in <file>&master-host;:&file-debian-private-archive;</file>, just <prgn>zgrep</prgn> for <em>#debian-private</em> in
+in the archives of debian-private in
+<file>master.debian.org:&file-debian-private-archive;</file>,
+just <prgn>zgrep</prgn> for <em>#debian-private</em> in
 all the files.
 	<p>
 There are other additional channels dedicated to specific subjects.
@@ -493,42 +523,60 @@ but it can not contain everything. Most of the other interesting documents
 are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
 Take the time to browse all the links, you will learn many more things.
 
-      <sect id="server-machines">Debian servers
+
+      <sect id="server-machines">Debian machines
+	<p>
+Debian has several computers working as servers, most of which serve
+critical functions in the Debian project. Most of the machines are used
+for porting activities, and they all have a permanent connection to the
+Internet.
+	<p>
+Most of the machines are available for individual developers to use,
+as long as the developers follow the rules set forth in the
+<url name="Debian Machine Usage Policies" id="&url-dmup;">.
 	<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.
+Generally speaking, you can use these machines 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 admins.  Usually these machines are run by
+volunteers.
+	<p>
+Please take care to protect your Debian passwords and SSH keys installed on
+Debian machines. Avoid login or upload methods which send passwords over
+the Internet in the clear, such as telnet, FTP, POP etc.
+	<p>
+Please do not put any material that doesn't relate to Debian on the Debian
+servers, unless you have prior permission.
+	<p>
+The current list of Debian machines is available at
+<url id="&url-devel-machines;">. That web page contains machine names,
+contact information, information about who can log in, SSH keys etc.
 	<p>
 If you have a problem with the operation of a Debian server, and you
 think that the system operators need to be notified of this problem,
-please find the contact address for the particular machine at <url
-id="&url-devel-machines;">.  If you have a non-operating problems
-(such as packages to be removed, suggestions for the web site, etc.),
+the Debian system administrator team is reachable at
+<email>debian-admin@lists.debian.org</email>.
+	<p>
+If you have a problem with a certain service, not related to the system
+administration (such as packages to be removed from the archive,
+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.
 
-      <sect1 id="servers-master">The master server
+      <sect1 id="servers-bugs">The bugs server
 	<p>
-<tt>&master-host;</tt> is the canonical location for the Bug Tracking
+<tt>bugs.debian.org</tt> is the canonical location for the Bug Tracking
 System (BTS).  If you plan on doing some statistical analysis or
 processing of Debian bugs, this would be the place to do it.  Please
 describe your plans on &email-debian-devel; before implementing
 anything, however, to reduce unnecessary duplication of effort or
 wasted processing time.
 	<p>
-All Debian developers have accounts on <tt>&master-host;</tt>.
-Please take care to protect your password to this machine.  Try to
-avoid login or upload methods which send passwords over the Internet
-in the clear.
-	<p>
-If you find a problem with <tt>&master-host;</tt> such as disk
-full, suspicious activity, or whatever, send an email to
-&email-debian-admin;.
+All Debian developers have accounts on <tt>bugs.debian.org</tt>.
 
       <sect1 id="servers-ftp-master">The ftp-master server
 	<p>
-The ftp-master server, <tt>&ftp-master-host;</tt> (or
-<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
+The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
 archive (excluding the non-US packages). Generally, package uploads
 go to this server; see <ref id="upload">.
 	<p>
@@ -537,34 +585,59 @@ bugs against the <package>ftp.debian.org</package> pseudo-package or
 an email to &email-ftpmaster;, but also see the procedures in
 <ref id="archive-manip">.
 
-      <sect1 id="servers-www">The WWW server
+      <sect1 id="servers-non-us">The non-US server
 	<p>
-The main web server, <tt>&www-host;</tt>, is also known as
-<tt>klecker.debian.org</tt>.  All developers are given accounts on this
-machine.
+The non-US server, <tt>non-us.debian.org</tt>,
+holds the canonical copy of the non-US part of the Debian archive.
+If you need to upload a package into one of the non-US sections, upload it
+to this server; see <ref id="upload-non-us">.
 	<p>
-If you have some Debian-specific information which you want to serve
-on the web, you can do this by putting material in the
-<file>public_html</file> directory under your home directory.  You should
-do this on <tt>klecker.debian.org</tt>. Any material you put in those areas
-are accessible via the URL
-<tt>http://people.debian.org/~<var>user-id</var>/</tt>.
-You should only use this particular location because it will be backed up,
-whereas on other hosts it won't. Please do not put any material on Debian
-servers not relating to Debian, unless you have prior permission.
-Send mail to &email-debian-devel; if you have any questions.
+Problems with the non-US package archive should generally be submitted as
+bugs against the <package>nonus.debian.org</package> pseudo-package (notice
+the lack of hyphen between "non" and "us" in the pseudo-package name
+&mdash; that's for backwards compatibility). Remember to check whether or
+not someone else has already reported the problem on the
+<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+
+      <sect1 id="servers-www">The www-master server
+	<p>
+The main web server is <tt>www-master.debian.org</tt>.
+It holds the official web pages, the face
+of Debian for most newbies.
 	<p>
 If you find a problem with the Debian web server, you should generally
 submit a bug against the pseudo-package,
-<package>www.debian.org</package>.  First check whether or not someone
+<package>www.debian.org</package>. Remember to check whether or not someone
 else has already reported the problem on the
 <url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
 
+      <sect1 id="servers-people">The people web server
+	<p>
+<tt>people.debian.org</tt> is the server used
+for developers' own web pages about anything related to Debian.
+	<p>
+If you have some Debian-specific information which you want to serve
+on the web, you can do this by putting material in the
+<file>public_html</file> directory under your home directory on
+<tt>people.debian.org</tt>.
+This will be accessible at the URL
+<tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
+	<p>
+You should only use this particular location because it will be backed up,
+whereas on other hosts it won't.
+	<p>
+Usually the only reason to use a different host is when you need to publish
+materials subject to the U.S. export restrictions, in which case you can use
+one of the other servers located outside the United States, such as the
+aforementioned <tt>non-us.debian.org</tt>.
+	<p>
+Send mail to &email-debian-devel; if you have any questions.
 
       <sect1 id="servers-cvs">The CVS server
 	<p>
-<tt>cvs.debian.org</tt> is also known as <tt>klecker.debian.org</tt>,
-discussed above.  If you need to use a publicly accessible CVS
+Our CVS server is located on <tt>cvs.debian.org</tt>.
+	<p>
+If you need to use a publicly 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.
 	  <p>
@@ -578,7 +651,7 @@ To request a CVS area, send a request via email to
 the Debian account that should own the CVS root area, and why you need it.
 
 
-      <sect1 id="devel-db">The Developers Database
+    <sect id="devel-db">The Developers Database
 	<p>
 The Developers Database, at <url id="&url-debian-db;">, is an LDAP
 directory for managing Debian developer attributes.  You can use this
@@ -611,21 +684,6 @@ interested in helping Debian.  As such, developers generally do not
 have accounts on these machines.
 
 
-      <sect id="other-machines">Other Debian developer 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">, there
-is a list of machines available to Debian developers at <url
-id="&url-devel-machines;">.
-
-
-
     <sect id="archive">The Debian archive
 	<p>
 The &debian-formal; distribution consists of a lot of packages
@@ -641,14 +699,15 @@ As you can see, the top-level directory contains two directories,
 packages actually are, and which is handled by the archive maintenance
 database and the accompanying programs. The former contains the
 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
-Each of those distribution directories is divided in equivalent
-subdirectories purpose of which is equal, so we will only explain how it
-looks in stable. The <file>Packages</file> and <file>Sources</file> files in the
+The <file>Packages</file> and <file>Sources</file> files in the
 distribution subdirectories can reference files in the <file>pool/</file>
-directory.
+directory. The directory tree below each of the distributions is arranged
+in an identical manner.  What we describe below for <em>stable</em> is
+equally applicable to the <em>unstable</em> and <em>testing</em>
+distributions. 
 	<p>
 <file>dists/stable</file> contains three directories, namely <file>main</file>,
-<file>contrib</file>, and <file>non-free</file>.
+<file>contrib</file>, and <file>non-free</file>. 
 	<p>
 In each of the areas, there is a directory for the source packages
 (<file>source</file>) and a directory for each supported architecture
@@ -887,7 +946,7 @@ New software which isn't likely to damage your system can go directly into
 <em>unstable</em>.
 	  <p>
 An alternative to <em>experimental</em> is to use your personal web space
-on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
+on <tt>people.debian.org</tt>.
 
 
       <sect1 id="codenames">Release code names
@@ -935,15 +994,15 @@ installing them in the Debian archive. It consists of a set of
 directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
 and <tt>&non-us-host;</tt>.
 	<p>
-Packages are uploaded by all the maintainers into an <file>unchecked</file>
-directory. This directory is scanned every 15 minutes by the katie script
-that verifies the integrity of the package and the cryptographic
-signature.  If the package is considered ready to be installed, it
-is moved into an <file>accepted</file> directory. If it is the first upload of
-the package then it is moved in a <file>new</file> directory waiting an
-approval of the ftpmasters. If the package contains files to be installed
-"by-hand" is is moved in the <file>byhand</file> directory waiting a manual
-installation by the ftpmasters. Otherwise, if any error has been detected,
+Packages are uploaded by all the maintainers into a directory called
+<file>unchecked</file>. This directory is scanned every 15 minutes by the katie script
+that verifies the integrity of the uploaded packages and the cryptographic
+signatures.  If the package is considered ready to be installed, it
+is moved into the <file>accepted</file> directory. If this is the first upload of
+the package, it is moved in the <file>new</file> directory, where it waits
+for an approval of the ftpmasters. If the package contains files to be installed
+"by-hand" is is moved in the <file>byhand</file> directory, where it waits
+for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
 the package is refused and is moved in the <file>reject</file> directory.
 	<p>
 Once the package is accepted the system sends a confirmation
@@ -1548,7 +1607,7 @@ maintenance software will process it by running <prgn>dinstall</prgn>
 on your changes file: <example>dinstall -n foo.changes</example>.
 Note that <prgn>dput</prgn> can do this for you automatically.
 
-	<sect2 id="upload-non-us">Uploading to <tt>non-US</tt> (pandora)
+	<sect2 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
@@ -1885,11 +1944,7 @@ absolutely necessary for someone other than the usual maintainer to
 make a release based on a new upstream version then the person making
 the release should start with the <var>debian-revision</var> value
 `0.1'.  The usual maintainer of a package should start their
-<var>debian-revision</var> numbering at `1'.  Note that if you do
-this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
-<tt>-sa</tt> switch to force the build system to pick up the new
-source package (normally it only looks for Debian revisions of '0' or
-'1' &mdash; it's not yet clever enough to know about `0.1').
+<var>debian-revision</var> numbering at `1'. 
 
 
 	<sect2 id="nmu-changelog">