<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+ <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
+]>
<chapter id="resources">
<title>Resources for Debian Developers</title>
<para>
<para>
Much of the conversation between Debian developers (and users) is managed
through a wide array of mailing lists we host at <literal><ulink
-url="http://lists.debian.org/">lists.debian.org</ulink></literal>. To find out
+url="http://&lists-host;/">&lists-host;</ulink></literal>. To find out
more on how to subscribe or unsubscribe, how to post and how not to post, where
to find old posts and how to search them, how to contact the list maintainers
and see various other information about the mailing lists, please read <ulink
-url="http://www.debian.org/MailingLists/"></ulink>. This section will only
+url="&url-debian-lists;"></ulink>. This section will only
cover aspects of mailing lists that are of particular interest to developers.
</para>
<section id="mailing-lists-rules">
</para>
<para>
Please read the <ulink
-url="http://www.debian.org/MailingLists/#codeofconduct">code of conduct</ulink>
+url="&url-debian-lists;#codeofconduct">code of conduct</ulink>
for more information.
</para>
</section>
<itemizedlist>
<listitem>
<para>
-<email>debian-devel-announce@lists.debian.org</email>, used to announce
+<email>debian-devel-announce@&lists-host;</email>, used to announce
important things to developers. All developers are expected to be subscribed
to this list.
</para>
</listitem>
<listitem>
<para>
-<email>debian-devel@lists.debian.org</email>, used to discuss various
+<email>debian-devel@&lists-host;</email>, used to discuss various
development related technical issues.
</para>
</listitem>
<listitem>
<para>
-<email>debian-policy@lists.debian.org</email>, where the Debian Policy is
+<email>debian-policy@&lists-host;</email>, where the Debian Policy is
discussed and voted on.
</para>
</listitem>
<listitem>
<para>
-<email>debian-project@lists.debian.org</email>, used to discuss various
+<email>debian-project@&lists-host;</email>, used to discuss various
non-technical issues related to the project.
</para>
</listitem>
</itemizedlist>
<para>
There are other mailing lists available for a variety of special topics; see
-<ulink url="http://lists.debian.org/"></ulink> for a list.
+<ulink url="http://&lists-host;/"></ulink> for a list.
</para>
</section>
<section id="mailing-lists-special">
<title>Special lists</title>
<para>
-<email>debian-private@lists.debian.org</email> is a special mailing list for
+<email>debian-private@&lists-host;</email> is a special mailing list for
private discussions amongst Debian developers. It is meant to be used for
posts which for whatever reason should not be published publicly. As such, it
is a low volume list, and users are urged not to use
-<email>debian-private@lists.debian.org</email> unless it is really necessary.
+<email>debian-private@&lists-host;</email> unless it is really necessary.
Moreover, do <emphasis>not</emphasis> 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 <literal>lists.debian.org</literal>
-and looking in the <filename>~debian/archive/debian-private</filename>
+can see them using your shell account on <literal>&lists-host;</literal>
+and looking in the <filename>&file-debian-private-archive;</filename>
directory.
</para>
<para>
-<email>debian-email@lists.debian.org</email> is a special mailing list used as
+<email>debian-email@&lists-host;</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.
more appropriate.
</para>
<para>
-If you decide that a regular mailing list on lists.debian.org is really what
+If you decide that a regular mailing list on &lists-host; is really what
you want, go ahead and fill in a request, following <ulink
-url="http://www.debian.org/MailingLists/HOWTO_start_list">the HOWTO</ulink>.
+url="&url-debian-lists-new;">the HOWTO</ulink>.
</para>
</section>
<para>
Since <emphasis>#debian-devel</emphasis> is an open channel, you should not
speak there of issues that are discussed in
-<email>debian-private@lists.debian.org</email>. There's another channel for
+<email>debian-private@&lists-host;</email>. There's another channel for
this purpose, it's called <emphasis>#debian-private</emphasis> and it's
protected by a key. This key is available in the archives of debian-private in
-<filename>master.debian.org:~debian/archive/debian-private/</filename>, just
+<filename>master.debian.org:&file-debian-private-archive;</filename>, just
<command>zgrep</command> for <emphasis>#debian-private</emphasis> in all the
files.
</para>
<para>
This document contains a lot of information which is useful to Debian
developers, but it cannot contain everything. Most of the other interesting
-documents are linked from <ulink url="http://www.debian.org/devel/">The
+documents are linked from <ulink url="&url-devel-docs;">The
Developers' Corner</ulink>. Take the time to browse all the links, you will
learn many more things.
</para>
<para>
Most of the machines are available for individual developers to use, as long as
the developers follow the rules set forth in the <ulink
-url="http://www.debian.org/devel/dmup">Debian Machine Usage Policies</ulink>.
+url="&url-devel-docs;dmup">Debian Machine Usage Policies</ulink>.
</para>
<para>
Generally speaking, you can use these machines for Debian-related purposes as
</para>
<para>
The current list of Debian machines is available at <ulink
-url="http://db.debian.org/machines.cgi"></ulink>. That web page contains
+url="&url-devel-machines;"></ulink>. That web page contains
machine names, contact information, information about who can log in, SSH keys
etc.
</para>
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, the Debian system
administrator team is reachable at
-<email>debian-admin@lists.debian.org</email>.
+<email>debian-admin@&lists-host;</email>.
</para>
<para>
If you have a problem with a certain service, not related to the system
<section id="servers-bugs">
<title>The bugs server</title>
<para>
-<literal>bugs.debian.org</literal> is the canonical location for the Bug
+<literal>&bugs-host;</literal> is the canonical location for the Bug
Tracking System (BTS).
</para>
<para>
<para>
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@lists.debian.org</email> before implementing anything,
+<email>debian-devel@&lists-host;</email> before implementing anything,
however, to reduce unnecessary duplication of effort or wasted processing time.
</para>
</section>
<section id="servers-ftp-master">
<title>The ftp-master server</title>
<para>
-The <literal>ftp-master.debian.org</literal> server holds the canonical copy of
+The <literal>&ftp-master-host;</literal> server holds the canonical copy of
the Debian archive (excluding the non-US packages). Generally, package uploads
go to this server; see <xref linkend="upload"/> .
</para>
</para>
<para>
Problems with the Debian FTP archive generally need to be reported as bugs
-against the <systemitem role="package">ftp.debian.org</systemitem>
+against the <systemitem role="package">&ftp-debian-org;</systemitem>
pseudo-package or an email to <email>ftpmaster@debian.org</email>, but also see
the procedures in <xref linkend="archive-manip"/> .
</para>
<section id="servers-non-us">
<title>The non-US server</title>
<para>
-The non-US server <literal>non-us.debian.org</literal> was discontinued with
+The non-US server <literal>&non-us-host;</literal> was discontinued with
the release of sarge. The pseudo-package <systemitem
role="package">nonus.debian.org</systemitem> still exists for now.
</para>
<para>
If you find a problem with the Debian web server, you should generally submit a
bug against the pseudo-package, <systemitem
-role="package">www.debian.org</systemitem>. Remember to check whether or not
+role="package">&www-debian-org;</systemitem>. Remember to check whether or not
someone else has already reported the problem to the <ulink
-url="http://bugs.debian.org/www.debian.org">Bug Tracking System</ulink>.
+url="http://&bugs-host;/&www-debian-org;">Bug Tracking System</ulink>.
</para>
</section>
one of the other servers located outside the United States.
</para>
<para>
-Send mail to <email>debian-devel@lists.debian.org</email> if you have any
+Send mail to <email>debian-devel@&lists-host;</email> if you have any
questions.
</para>
</section>
Generally, <literal>cvs.debian.org</literal> offers a combination of local CVS
access, anonymous client-server read-only access, and full client-server access
through <command>ssh</command>. Also, the CVS area can be accessed read-only
-via the Web at <ulink url="http://cvs.debian.org/"></ulink>.
+via the Web at <ulink url="&url-cvsweb;"></ulink>.
</para>
<para>
To request a CVS area, send a request via email to
can use them like this:
</para>
<screen>
-% dchroot unstable
+vore$ dchroot unstable
Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable
</screen>
<para>
In all chroots, the normal user home directories are available. You can find
out which chroots are available via
-<literal>http://db.debian.org/machines.cgi</literal>.
+<literal>&url-devel-machines;</literal>.
</para>
</section>
<section id="devel-db">
<title>The Developers Database</title>
<para>
-The Developers Database, at <ulink url="https://db.debian.org/"></ulink>, is an
+The Developers Database, at <ulink url="&url-debian-db;"></ulink>, is an
LDAP directory for managing Debian developer attributes. You can use this
resource to search the list of Debian developers. Part of this information is
also available through the finger service on Debian servers, try
<command>finger yourlogin@db.debian.org</command> to see what it reports.
</para>
<para>
-Developers can <ulink url="https://db.debian.org/login.html">log into the
+Developers can <ulink url="&url-debian-db-login;">log into the
database</ulink> to change various information about themselves, such as:
</para>
<itemizedlist>
<para>
personal information such as your address, country, the latitude and longitude
of the place where you live for use in <ulink
-url="http://www.debian.org/devel/developers.loc">the world map of Debian
+url="&url-devel-docs;developers.loc">the world map of Debian
developers</ulink>, phone and fax numbers, IRC nickname and web page
</para>
</listitem>
<para>
Most of the information is not accessible to the public, naturally. For more
information please read the online documentation that you can find at <ulink
-url="http://db.debian.org/doc-general.html"></ulink>.
+url="&url-debian-db-doc;"></ulink>.
</para>
<para>
Developers can also submit their SSH keys to be used for authorization on the
official Debian machines, and even add new *.debian.net DNS entries. Those
features are documented at <ulink
-url="http://db.debian.org/doc-mail.html"></ulink>.
+url="&url-debian-db-mail-gw;"></ulink>.
</para>
</section>
<section id="archive">
<title>The Debian archive</title>
<para>
-The Debian GNU/Linux distribution consists of a lot of packages
-(<filename>.deb</filename>'s, currently around 9000) and a few additional files
+The &debian-formal; distribution consists of a lot of packages
+(<filename>.deb</filename>'s, currently around &number-of-pkgs;) and a few additional files
(such as documentation and installation disk images).
</para>
<para>
Here is an example directory tree of a complete Debian archive:
</para>
-<screen>
-/stable/main/
-dists/stable/main/binary-i386/
-dists/stable/main/binary-m68k/
-dists/stable/main/binary-alpha/
- ...
-dists/stable/main/source/
- ...
-dists/stable/main/disks-i386/
-dists/stable/main/disks-m68k/
-dists/stable/main/disks-alpha/
- ...
-
-dists/stable/contrib/
-dists/stable/contrib/binary-i386/
-dists/stable/contrib/binary-m68k/
-dists/stable/contrib/binary-alpha/
- ...
-dists/stable/contrib/source/
-
-dists/stable/non-free/
-dists/stable/non-free/binary-i386/
-dists/stable/non-free/binary-m68k/
-dists/stable/non-free/binary-alpha/
- ...
-dists/stable/non-free/source/
-
-dists/testing/
-dists/testing/main/
- ...
-dists/testing/contrib/
- ...
-dists/testing/non-free/
- ...
-
-dists/unstable
-dists/unstable/main/
- ...
-dists/unstable/contrib/
- ...
-dists/unstable/non-free/
- ...
-
-pool/
-pool/main/a/
-pool/main/a/apt/
- ...
-pool/main/b/
-pool/main/b/bash/
- ...
-pool/main/liba/
-pool/main/liba/libalias-perl/
- ...
-pool/main/m/
-pool/main/m/mailx/
- ...
-pool/non-free/n/
-pool/non-free/n/netscape/
- ...
-</screen>
+&sample-dist-dirtree;
<para>
As you can see, the top-level directory contains two directories,
<filename>dists/</filename> and <filename>pool/</filename>. The latter is a
<title>Sections</title>
<para>
The <emphasis>main</emphasis> section of the Debian archive is what makes up
-the <emphasis role="strong">official Debian GNU/Linux distribution</emphasis>.
+the <emphasis role="strong">official &debian-formal; distribution</emphasis>.
The <emphasis>main</emphasis> section is official because it fully complies
with all our guidelines. The other two sections do not, to different degrees;
as such, they are <emphasis role="strong">not</emphasis> officially part of
-Debian GNU/Linux.
+&debian-formal;.
</para>
<para>
Every package in the main section must fully comply with the <ulink
-url="http://www.debian.org/social_contract#guidelines">Debian Free Software
+url="&url-dfsg;">Debian Free Software
Guidelines</ulink> (DFSG) and with all other policy requirements as described
-in the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+in the <ulink url="&url-debian-policy;">Debian Policy
Manual</ulink>. The DFSG is our definition of “free software.” Check out
the Debian Policy Manual for details.
</para>
software packages.
</para>
<para>
-The <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+The <ulink url="&url-debian-policy;">Debian Policy
Manual</ulink> contains a more exact definition of the three sections. The
above discussion is just an introduction.
</para>
<emphasis>mipsel</emphasis> and <emphasis>sh</emphasis> as of this writing.
</para>
<para>
-Debian GNU/Linux 1.3 is only available as <emphasis>i386</emphasis>. Debian
+&debian-formal; 1.3 is only available as <emphasis>i386</emphasis>. Debian
2.0 shipped for <emphasis>i386</emphasis> and <emphasis>m68k</emphasis>
architectures. Debian 2.1 ships for the <emphasis>i386</emphasis>,
<emphasis>m68k</emphasis>, <emphasis>alpha</emphasis>, and
</para>
<para>
Information for developers and users about the specific ports are available at
-the <ulink url="http://www.debian.org/ports/">Debian Ports web pages</ulink>.
+the <ulink url="&url-debian-ports;">Debian Ports web pages</ulink>.
</para>
</section>
new copy is created for the new <emphasis>testing</emphasis>, and the previous
<emphasis>stable</emphasis> is renamed to <emphasis>oldstable</emphasis> and
stays there until it is finally archived. On archiving, the contents are moved
-to <literal>archive.debian.org</literal>).
+to <literal>&archive-host;</literal>).
</para>
<para>
This development cycle is based on the assumption that the
<manvolnum>5</manvolnum> </citerefentry> lines for
<emphasis>experimental</emphasis>:
</para>
-<screen>
- http://ftp.<replaceable>xy</replaceable>.debian.org/debian/ experimental main
+<programlisting>
+deb http://ftp.<replaceable>xy</replaceable>.debian.org/debian/ experimental main
deb-src http://ftp.<replaceable>xy</replaceable>.debian.org/debian/ experimental main
-</screen>
+</programlisting>
<para>
If there is a chance that the software could do grave damage to a system, it is
likely to be better to put it into <emphasis>experimental</emphasis>. For
<para>
All the information on Debian mirrors, including a list of the available public
FTP/HTTP servers, can be found at <ulink
-url="http://www.debian.org/mirror/"></ulink>. This useful page also includes
+url="url-debian-mirroring"></ulink>. This useful page also includes
information and tools which can be helpful if you are interested in setting up
your own mirror, either for internal or public access.
</para>
<para>
The Incoming system is responsible for collecting updated packages and
installing them in the Debian archive. It consists of a set of directories and
-scripts that are installed on <literal>ftp-master.debian.org</literal>.
+scripts that are installed on <literal>&ftp-master-host;</literal>.
</para>
<para>
Packages are uploaded by all the maintainers into a directory called
<filename>.changes</filename> file that you uploaded to the appropriate mailing
lists. If a package is released with the <literal>Distribution:</literal> set
to `stable', the announcement is sent to
-<email>debian-changes@lists.debian.org</email>. If a package is released with
+<email>debian-changes@&lists-host;</email>. If a package is released with
<literal>Distribution:</literal> set to `unstable' or `experimental', the
announcement will be posted to
-<email>debian-devel-changes@lists.debian.org</email> instead.
+<email>debian-devel-changes@&lists-host;</email> instead.
</para>
<para>
Though ftp-master is restricted, a copy of the installation is available to all
-developers on <literal>merkel.debian.org</literal>.
+developers on <literal>&ftp-master-mirror;</literal>.
</para>
<!-- FIXME: delete it or keep it for historical purposes?
<para>
of integration with your upload tool. For instance, if you use
<command>dupload</command> (see <xref linkend="dupload"/>), you can add this
snippet to your configuration file:
-<screen>
+<programlisting>
$delay = ($ENV{DELAY} || 7);
$cfg{'delayed'} = {
fqdn => "&ftp-master-host;",
login => "yourdebianlogin",
- incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
+ incoming => "/org/&ftp-debian-org;/incoming/DELAYED/$delay-day/",
dinstall_runs => 1,
method => "scpb"
};
-</screen>
+</programlisting>
Once you've made that change, <command>dupload</command> can be used to
easily upload a package in one of the delayed directories:
<literal>DELAY=5 dupload -X-to delayed <changes-file></literal>
<title>On the web</title>
<para>
Each package has several dedicated web pages.
-<literal>http://packages.debian.org/<replaceable>package-name</replaceable></literal>
+<literal>http://&packages-host;/<replaceable>package-name</replaceable></literal>
displays each version of the package available in the various distributions.
Each version links to a page which provides information, including the package
description, the dependencies, and package download links.
<para>
The bug tracking system tracks bugs for each package. You can view the bugs of
a given package at the URL
-<literal>http://bugs.debian.org/<replaceable>package-name</replaceable></literal>.
+<literal>http://&bugs-host;/<replaceable>package-name</replaceable></literal>.
</para>
</section>
<title>The <command>madison</command> utility</title>
<para>
<command>madison</command> is a command-line utility that is available on
-<literal>ftp-master.debian.org</literal>, and on the mirror on
-<literal>merkel.debian.org</literal>. It uses a single argument corresponding
+<literal>&ftp-master-host;</literal>, and on the mirror on
+<literal>&ftp-master-mirror;</literal>. It uses a single argument corresponding
to a package name. In result it displays which version of the package is
available for each architecture and distribution combination. An example will
explain it better.
<term><literal>bts-control</literal></term>
<listitem>
<para>
-The email notifications from <email>control@bugs.debian.org</email> about bug
+The email notifications from <email>control@&bugs-host;</email> about bug
report status changes.
</para>
</listitem>
<para>
Any non-automatic email sent to the PTS by people who wanted to contact the
subscribers of the package. This can be done by sending mail to
-<literal><replaceable>sourcepackage</replaceable>@packages.qa.debian.org</literal>.
+<literal><replaceable>sourcepackage</replaceable>@&pts-host;</literal>.
In order to prevent spam, all messages sent to these addresses must contain the
<literal>X-PTS-Approved</literal> header with a non-empty value.
</para>
<listitem>
<para>
<literal>bts-control</literal>: reply to mails sent to
-<email>control@bugs.debian.org</email>
+<email>control@&bugs-host;</email>
</para>
</listitem>
<listitem>
<title>Filtering PTS mails</title>
<para>
Once you are subscribed to a package, you will get the mails sent to
-<literal><replaceable>sourcepackage</replaceable>@packages.qa.debian.org</literal>.
+<literal><replaceable>sourcepackage</replaceable>@&pts-host;</literal>.
Those mails have special headers appended to let you filter them in a special
mailbox (e.g. with <command>procmail</command>). The added headers are
<literal>X-Loop</literal>, <literal>X-PTS-Package</literal>,
<systemitem role="package">dpkg</systemitem> package:
</para>
<screen>
--Loop: dpkg@packages.qa.debian.org
+X-Loop: dpkg@&pts-host;
X-PTS-Package: dpkg
X-PTS-Keyword: upload-source
X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
<para>
Once you set up the CVS repository to generate commit notifications, you just
have to make sure it sends a copy of those mails to
-<literal><replaceable>sourcepackage</replaceable>_cvs@packages.qa.debian.org</literal>.
+<literal><replaceable>sourcepackage</replaceable>_cvs@&pts-host;</literal>.
Only the people who accept the <emphasis>cvs</emphasis> keyword will receive
these notifications.
</para>
<title>The PTS web interface</title>
<para>
The PTS has a web interface at <ulink
-url="http://packages.qa.debian.org/"></ulink> that puts together a lot of
+url="http://&pts-host;/"></ulink> that puts together a lot of
information about each source package. It features many useful links (BTS, QA
stats, contact information, DDTP translation status, buildd logs) and gathers
much more information from various places (30 latest changelog entries, testing
<para>
You can jump directly to the web page concerning a specific source package with
a URL like
-<literal>http://packages.qa.debian.org/<replaceable>sourcepackage</replaceable></literal>.
+<literal>http://&pts-host;/<replaceable>sourcepackage</replaceable></literal>.
</para>
<para>
This web interface has been designed like a portal for the development of
information section:
</para>
<screen>
-: Raphael Hertzog <hertzog@debian.org>
+From: Raphael Hertzog <hertzog@debian.org>
To: pts-static-news@qa.debian.org
Subject: Browse debian-cd CVS repository with cvsweb
Package: debian-cd
-Url: http://cvs.debian.org/debian-cd/
+Url: &url-cvsweb;debian-cd/
</screen>
<para>
The second one is an announcement sent to a mailing list which is also sent to
</para>
<screen>
: Raphael Hertzog <hertzog@debian.org>
-To: debian-gtk-gnome@lists.debian.org
+To: debian-gtk-gnome@&lists-host;
Bcc: pts-news@qa.debian.org
Subject: Galeon 2.0 backported for woody
X-PTS-Package: galeon
<title>Developer's packages overview</title>
<para>
A QA (quality assurance) web portal is available at <ulink
-url="http://qa.debian.org/developer.php"></ulink> which displays a table
+url="&url-debian-qa;developer.php"></ulink> which displays a table
listing all the packages of a single developer (including those where the party
is listed as a co-maintainer). The table gives a good summary about the
developer's packages: number of bugs by severity, list of available versions in
Since October of 2002, HP has sponsored a subscription to LWN for all
interested Debian developers. Details on how to get access to this benefit are
in <ulink
-url="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html"></ulink>.
+url="http://&lists-host;/debian-devel-announce/2002/10/msg00018.html"></ulink>.
</para>
</section>
~ianmdlvl / developers-reference.git / blobdiff