# Makefile, used for the developers-reference in DocBook XML
-SOURCES := $(wildcard *.dbk)
+SOURCES := $(wildcard *.dbk *.ent)
FORMATS := html txt pdf
LANGS := fr ja
XP=xsltproc --nonet --novalid --xinclude
XL=xmllint --nonet --noout --postvalid --xinclude
# fop is currently in contrib, but can go to main, see #366783
-# alternatives: docbook2pdf (seems to die on UTF-8), dblatex (0.2.4
-# just hangs here) and xmllint (not mature enough, waits in NEW)
+# Alternatives:
+# - dblatex (0.2.6 has a minor problem with programlisting inside of
+# footnote, and a major one with lang="ja");
+# - docbook2pdf (seems to die on UTF-8, #431085); and
+# - xmllint (not mature enough, waits in NEW, #182445)
FOP=fop
# The "-k 0" should be removed as soon as the translations are ready
TRANSLATE=po4a-translate -f docbook -k 0
all: $(TARGETS)
.PHONY: validate
-validate:
+validate: $(SOURCES)
$(XL) index.dbk
+%/validate: $(addprefix %/,$(SOURCES))
+ cd $(@D) && $(XL) index.dbk
+
.PHONY: developers-reference.html %/developers-reference.html
developers-reference.html: $(PWD)/index.html
%/developers-reference.html: $(addprefix %/,index.html)
.PRECIOUS: %/index.html
index.html: $(PWD)/developers-reference.html
%/index.html: $(addprefix %/,$(SOURCES))
- mkdir -p $(@D) || true
cd $(@D) && $(XP) $(DBK2HTML) index.dbk
# There must be an easier way than recursive make!
-.PRECIOUS: %.dbk
+.PRECIOUS: %.dbk %.ent
ifndef LINGUA
-%.dbk: FORCE
- [ "$$LINGUA" = . ] || make $@ LINGUA=$(@D)
+%.dbk %.ent: FORCE
+ [ "$$LINGUA" = . ] || $(MAKE) $@ LINGUA=$(@D)
FORCE:
else
$(LINGUA)/%.dbk: %.dbk $(patsubst %.dbk,po4a/$(LINGUA)/%.po,%.dbk)
$(TRANSLATE) -m $< -p po4a/$(@:.dbk=.po) -l $@
+
+$(LINGUA)/%.ent: %.ent
+ cd $(@D) && ln -sf ../$(@F) .
endif
developers-reference.txt: $(PWD)/developers-reference.txt
<?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="best-pkging-practices">
<title>Best Packaging Practices</title>
<para>
Debian's quality is largely due to the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink>, which
+url="&url-debian-policy;">Debian Policy</ulink>, which
defines explicit baseline requirements which all Debian packages must fulfill.
Yet there is also a shared history of experience which goes beyond the Debian
Policy, an accumulation of years of experience in packaging. Many very
<para>
The following practices are relevant to the <filename>debian/control</filename>
file. They supplement the <ulink
-url="http://www.debian.org/doc/debian-policy/ch-binary.html#s-descriptions">Policy
+url="&url-debian-policy;ch-binary.html#s-descriptions">Policy
on package descriptions</ulink>.
</para>
<para>
</para>
<para>
If you are having problems writing your description, you may wish to send it
-along to <email>debian-l10n-english@lists.debian.org</email> and request
+along to <email>debian-l10n-english@&lists-host;</email> and request
feedback.
</para>
</section>
modes for checking <filename>debian/control</filename> files:
</para>
<screen>
- -d american -g debian/control
+ispell -d american -g debian/control
</screen>
<screen>
- -d en -D -c debian/control
+aspell -d en -D -c debian/control
</screen>
<para>
Users usually expect these questions to be answered in the package description:
<para>
Note the spaces prepending the line, which serves to break the lines correctly.
To see an example of how this displays, see <ulink
-url="http://packages.debian.org/unstable/web/wml"></ulink>.
+url="http://&packages-host;/unstable/web/wml"></ulink>.
</para>
<para>
If there is no home page for the software, this should naturally be left out.
<para>
Note that we expect this field will eventually be replaced by a proper
<filename>debian/control</filename> field understood by <command>dpkg</command>
-and <literal>packages.debian.org</literal>. If you don't want to bother
+and <literal>&packages-host;</literal>. If you don't want to bother
migrating the home page from the description to this field, you should probably
wait until that is available. Please make sure that this line matches the
regular expression <literal>/^ Homepage: [^ ]*$/</literal>, as this allows
-<filename>packages.debian.org</filename> to parse it correctly.
+<filename>&packages-host;</filename> to parse it correctly.
</para>
</section>
<title>Best practices for <filename>debian/changelog</filename></title>
<para>
The following practices supplement the <ulink
-url="http://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs">Policy
+url="&url-debian-policy;ch-docs.html#s-changelogs">Policy
on changelog files</ulink>.
</para>
<section id="bpp-changelog-do">
is an example of a real NEWS.Debian file:
</para>
<screen>
- (3.0pl1-74) unstable; urgency=low
+cron (3.0pl1-74) unstable; urgency=low
The checksecurity script is no longer included with the cron package:
it now has its own package, checksecurity. If you liked the
<para>
FIXME: presentation of cvs-buildpackage, updating sources
via CVS (debian/rules refresh).
-<ulink url="http://www.debian.org/devel/cvs_packages">"http://www.debian.org/devel/cvs_packages"</ulink>
+<ulink url="&url-devel-docs;cvs_packages">"&url-devel-docs;cvs_packages"</ulink>
</para>
</section>
-->
<filename>debian/postrm</filename>. These scripts take care of any package
installation or deinstallation setup which isn't handled merely by the creation
or removal of files and directories. The following instructions supplement the
-<ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink>.
+<ulink url="&url-debian-policy;">Debian Policy</ulink>.
</para>
<para>
Maintainer scripts must be idempotent. That means that you need to make sure
If you need to check for the existence of a command, you should use something
like
</para>
-<screen>
- [ -x /usr/sbin/install-docs ]; then ...
-</screen>
+<programlisting>if [ -x /usr/sbin/install-docs ]; then ...</programlisting>
<para>
If you don't wish to hard-code the path of a command in your maintainer script,
the following POSIX-compliant shell function may help:
</para>
-<screen>
-() {
- OLDIFS=$IFS
- IFS=:
- for p in $PATH; do
- if [ -x $p/$* ]; then
- IFS=$OLDIFS
- return 0
- fi
- done
- IFS=$OLDIFS
- return 1
-}
-</screen>
+&example-pathfind;
<para>
You can use this function to search <literal>$PATH</literal> for a command
name, passed as an argument. It returns true (zero) if the command was found,
properly phrased templates may not be easy for them.
</para>
<para>
-Please use (and abuse) <email>debian-l10n-english@lists.debian.org</email>
+Please use (and abuse) <email>debian-l10n-english@&lists-host;</email>
mailing list. Have your templates proofread.
</para>
<para>
</para>
<para>
If in doubt, you may also contact the translation team for a given language
-(debian-l10n-xxxxx@lists.debian.org), or the
-<email>debian-i18n@lists.debian.org</email> mailing list.
+(debian-l10n-xxxxx@&lists-host;), or the
+<email>debian-i18n@&lists-host;</email> mailing list.
</para>
<para>
-Calls for translations posted to <email>debian-i18n@lists.debian.org</email>
+Calls for translations posted to <email>debian-i18n@&lists-host;</email>
with the <filename>debian/po/templates.pot</filename> file attached or
referenced in a URL are encouraged. Be sure to mentions in these calls for new
translations which languages you have existing translations for, in order to
using (needs the <systemitem role="package">gettext</systemitem> package
installed):
</para>
-<screen>
- i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
---statistics $i; done
-</screen>
+<programlisting>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null
+--statistics $i; done</programlisting>
</listitem>
<listitem>
<para>
<para>
use the following command:
</para>
-<screen>
- i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done
-</screen>
+<programlisting>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</programlisting>
</listitem>
<listitem>
<para>
Example, taken from the geneweb package templates:
</para>
<screen>
-: geneweb/lang
+Template: geneweb/lang
Type: select
__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
# This is the default choice. Translators may put their own language here
can see what needs to be retranslated. It is recommended that the translated
documentation maintain a note about what source control revision the
translation is based on. An interesting system is provided by <ulink
-url="http://cvs.debian.org/boot-floppies/documentation/doc-check?rev=HEAD\|[amp
+url="&url-cvsweb;boot-floppies/documentation/doc-check?rev=HEAD\|[amp
]\|content-type=text/vnd.viewcvs-markup">doc-check</ulink> in the <systemitem
role="package">boot-floppies</systemitem> package, which shows an overview of
the translation status for any given language, using structured comments for
especially on more volatile architectures. Some very good packaging practices
for any package using <command>autoconf</command> and/or
<command>automake</command> have been synthesized in
-<filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename> from the
+&file-bpp-autotools; from the
<systemitem role="package">autotools-dev</systemitem> package. You're strongly
encouraged to read this file and to follow the given recommendations.
</para>
</para>
<para>
Good practices for library packaging have been grouped in <ulink
-url="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/">the library
+url="&url-libpkg-guide;">the library
packaging guide</ulink>.
</para>
</section>
<title>Documentation</title>
<para>
Be sure to follow the <ulink
-url="http://www.debian.org/doc/debian-policy/ch-docs.html">Policy on
+url="&url-debian-policy;ch-docs.html">Policy on
documentation</ulink>.
</para>
<para>
<listitem>
<para>
Perl related packages have a <ulink
-url="http://www.debian.org/doc/packaging-manuals/perl-policy/">Perl
+url="&url-perl-policy;">Perl
policy</ulink>, some examples of packages following that policy are <systemitem
role="package">libdbd-pg-perl</systemitem> (binary perl module) or <systemitem
role="package">libmldbm-perl</systemitem> (arch independent perl module).
<listitem>
<para>
Emacs related packages have the <ulink
-url="http://www.debian.org/doc/packaging-manuals/debian-emacs-policy">emacs
+url="&url-emacs-policy;">emacs
policy</ulink>.
</para>
</listitem>
<listitem>
<para>
Java related packages have their <ulink
-url="http://www.debian.org/doc/packaging-manuals/java-policy/">java
+url="&url-java-policy;">java
policy</ulink>.
</para>
</listitem>
<para>
Lisp packages should register themselves with <systemitem
role="package">common-lisp-controller</systemitem>, about which see
-<filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>.
+&file-lisp-controller;.
</para>
</listitem>
<!-- TODO: mozilla extension policy, once that becomes available -->
this trick:
</para>
<para>
-If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the name
+If you set <varname>LOCPATH</varname> to the equivalent of <literal>/usr/lib/locale</literal>, and <varname>LC_ALL</varname> to the name
of the locale you generate, you should get what you want without being root.
Something like this:
</para>
<screen>
-=debian/tmpdir/usr/lib/locale
+LOCALE_PATH=debian/tmpdir/usr/lib/locale
LOCALE_NAME=en_IN
LOCALE_CHARSET=UTF-8
<para>
So, when you are creating such a package, please make sure to add this text to
your short description. If you are looking for examples, just run:
-</para>
-<screen>
--cache search .|grep dummy
-</screen>
-<para>
-or
-</para>
-<screen>
--cache search .|grep transitional
-</screen>
-<para>
-.
+<command>apt-cache search .|grep dummy</command> or
+<command>apt-cache search .|grep transitional</command>.
</para>
</section>
It unpacks the tarball in an empty temporary directory by doing
</para>
<screen>
- path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf -
+zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf -
</screen>
</listitem>
<listitem>
<literal>get-orig-source</literal> target in your
<filename>debian/rules</filename> file that repeats the process, as described
in the Policy Manual, <ulink
-url="http://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules">Main
+url="&url-debian-policy;ch-source.html#s-debianrules">Main
building script: debian/rules</ulink>.
</para>
</listitem>
Note that you don't need to depend on <systemitem
role="package">sharutils</systemitem> to get the <command>uudecode</command>
program if you use <command>perl</command>'s <literal>pack</literal> function.
-The code could look like </para> <screen> -file: perl -ne 'print(pack u, $$_);'
-$(file) > $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, $$_);'
-$(file).uuencoded > $(file) </screen> </footnote>. The file would then be
+The code could look like
+</para>
+&example-uu;
+</footnote>. The file would then be
decoded and copied to its place during the build process. Thus the change will
be visible quite easy.
</para>
debugging symbols for, and this dependency should be versioned. For example:
</para>
<screen>
-: libfoo-dbg (= ${binary:Version})
+Depends: libfoo-dbg (= ${binary:Version})
</screen>
</section>
<?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="beyond-pkging">
<title>Beyond Packaging</title>
<para>
in other developers' packages improves the quality of Debian.
</para>
<para>
-Read the <ulink url="http://www.debian.org/Bugs/Reporting">instructions for
+Read the <ulink url="&url-bts-report;">instructions for
reporting bugs</ulink> in the Debian <ulink
-url="http://www.debian.org/Bugs/">bug tracking system</ulink>.
+url="&url-bts;">bug tracking system</ulink>.
</para>
<para>
Try to submit the bug from a normal user account at which you are likely to
<para>
Make sure the bug is not already filed against a package. Each package has a
bug list easily reachable at
-<literal>http://bugs.debian.org/<replaceable>packagename</replaceable></literal>
+<literal>http://&bugs-host;/<replaceable>packagename</replaceable></literal>
Utilities like <citerefentry> <refentrytitle>querybts</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> can also provide you with this
information (and <command>reportbug</command> will usually invoke
reports that you submitted. Take this opportunity to close those that you
can't reproduce anymore. To find out all the bugs you submitted, you just have
to visit
-<literal>http://bugs.debian.org/from:<replaceable><your-email-addr></replaceable></literal>.
+<literal>http://&bugs-host;/from:<replaceable><your-email-addr></replaceable></literal>.
</para>
<section id="submit-many-bugs">
<title>Reporting lots of bugs at once (mass bug filing)</title>
</para>
<para>
If you report more than 10 bugs on the same topic at once, it is recommended
-that you send a message to <email>debian-devel@lists.debian.org</email>
+that you send a message to <email>debian-devel@&lists-host;</email>
describing your intention before submitting the report, and mentioning the fact
in the subject of your mail. This will allow other developers to verify that
the bug is a real problem. In addition, it will help prevent a situation in
Please use the programms <command>dd-list</command> and if appropriate
<command>whodepends</command> (from the package devscripts) to generate a list
of all affected packages, and include the output in your mail to
-<email>debian-devel@lists.debian.org</email>.
+<email>debian-devel@&lists-host;</email>.
</para>
<para>
Note that when sending lots of bugs on the same subject, you should send the
-bug report to <email>maintonly@bugs.debian.org</email> so that the bug report
+bug report to <email>maintonly@&bugs-host;</email> so that the bug report
is not forwarded to the bug distribution mailing list.
</para>
</section>
should consider orphaning some of your packages (see <xref
linkend="orphaning"/> ). Alternatively, you may ask the help of other people
in order to catch up with the backlog of bugs that you have (you can ask for
-help on <email>debian-qa@lists.debian.org</email> or
-<email>debian-devel@lists.debian.org</email>). At the same time, you can look
+help on <email>debian-qa@&lists-host;</email> or
+<email>debian-devel@&lists-host;</email>). At the same time, you can look
for co-maintainers (see <xref linkend="collaborative-maint"/> ).
</para>
</section>
<para>
From time to time the QA group organizes bug squashing parties to get rid of as
many problems as possible. They are announced on
-<email>debian-devel-announce@lists.debian.org</email> and the announcement
+<email>debian-devel-announce@&lists-host;</email> and the announcement
explains which area will be the focus of the party: usually they focus on
release critical bugs but it may happen that they decide to help finish a major
upgrade (like a new perl version which requires recompilation of all the binary
<para>
Looking up the email address of the maintainer for the package can be
distracting. Fortunately, there is a simple email alias,
-<literal><package>@packages.debian.org</literal>, which provides a way to
+<literal><package>@&packages-host;</literal>, which provides a way to
email the maintainer, whatever their individual email address (or addresses)
may be. Replace <literal><package></literal> with the name of a source
or a binary package.
<para>
You may also be interested in contacting the persons who are subscribed to a
given source package via <xref linkend="pkg-tracking-system"/> . You can do so
-by using the <literal><package>@packages.qa.debian.org</literal> email
+by using the <literal><package>@&pts-host;</literal> email
address.
</para>
<!-- FIXME: moo@packages.d.o is easily confused with moo@packages.qa.d.o -->
QA group contacts an inactive maintainer or finds more information about one,
this is recorded in the MIA database. This system is available in
/org/qa.debian.org/mia on the host qa.debian.org, and can be queried with a
-tool known as <command>mia-query</command>. Use
-</para>
-<screen>
--query --help
-</screen>
-<para>
+tool known as <command>mia-query</command>. Use <command>mia-query --help</command>
to see how to query the database. If you find that no information has been
recorded about an inactive maintainer yet, or that you can add more
information, you should generally proceed as follows.
<listitem>
<para>
The echelon information available through the <ulink
-url="https://db.debian.org/">developers' LDAP database</ulink>, which indicates
+url="&url-debian-db;">developers' LDAP database</ulink>, which indicates
when the developer last posted to a Debian mailing list. (This includes
uploads via debian-*-changes lists.) Also, remember to check whether the
maintainer is marked as on vacation in the database.
</para>
<para>
It is also allowed to post a query to
-<email>debian-devel@lists.debian.org</email>, asking if anyone is aware of the
+<email>debian-devel@&lists-host;</email>, asking if anyone is aware of the
whereabouts of the missing maintainer. Please Cc: the person in question.
</para>
<para>
Once the package meets Debian standards, build and sign it with
</para>
<screen>
--buildpackage -k<replaceable>KEY-ID</replaceable>
+dpkg-buildpackage -k<replaceable>KEY-ID</replaceable>
</screen>
<para>
before uploading it to the incoming directory. Of course, you can also use any
<title>Advocating new developers</title>
<para>
See the page about <ulink
-url="http://www.debian.org/devel/join/nm-advocate">advocating a prospective
+url="&url-devel-docs;join/nm-advocate">advocating a prospective
developer</ulink> at the Debian web site.
</para>
</section>
<title>Handling new maintainer applications</title>
<para>
Please see <ulink
-url="http://www.debian.org/devel/join/nm-amchecklist">Checklist for Application
+url="&url-devel-docs;join/nm-amchecklist">Checklist for Application
Managers</ulink> at the Debian web site.
</para>
</section>
--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- common entities file
+
+ Bits of text which are language independent. In some cases it
+ makes sense to break these out because repetitively maintaining
+ them in different translations of the Developer's Reference is
+ wasteful. In other cases, the data is rather volatile and
+ breaking it out make maintenance easier.
+ -->
+
+<!-- volatile information -->
+
+<!ENTITY number-of-pkgs "9000">
+<!ENTITY number-of-maintainers "900">
+
+<!ENTITY number-of-arches "12">
+
+<!-- standard information -->
+<!ENTITY fsf-addr "Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA">
+<!ENTITY file-GPL "<filename>/usr/share/common-licenses/GPL</filename>">
+<!ENTITY debian-formal "Debian GNU/Linux">
+
+<!--
+ URLs, Debian
+ -->
+<!ENTITY www-debian-org "www.debian.org">
+<!ENTITY ftp-debian-org "ftp.debian.org">
+<!ENTITY lists-host "lists.debian.org">
+<!ENTITY archive-host "archive.debian.org">
+<!ENTITY keyserver-host "keyring.debian.org">
+<!ENTITY packages-host "packages.debian.org">
+<!ENTITY bugs-host "bugs.debian.org">
+<!ENTITY pts-host "packages.qa.debian.org">
+<!ENTITY ftp-master-host "ftp-master.debian.org">
+<!ENTITY ftp-master-mirror "merkel.debian.org">
+<!ENTITY non-us-host "non-us.debian.org">
+<!ENTITY upload-queue "/pub/UploadQueue/">
+
+<!ENTITY url-debian-policy "http://&www-debian-org;/doc/debian-policy/">
+<!ENTITY url-perl-policy "http://&www-debian-org;/doc/packaging-manuals/perl-policy/">
+<!ENTITY url-emacs-policy "http://&www-debian-org;/doc/packaging-manuals/debian-emacs-policy">
+<!ENTITY url-java-policy "http://&www-debian-org;/doc/packaging-manuals/java-policy/">
+<!ENTITY url-libpkg-guide "http://www.netfort.gr.jp/~dancer/column/libpkg-guide/">
+
+<!ENTITY url-social-contract "http://&www-debian-org;/social_contract">
+<!ENTITY url-constitution "http://&www-debian-org;/devel/constitution">
+<!ENTITY url-dfsg "&url-social-contract;#guidelines">
+<!ENTITY url-debian-lists "http://&www-debian-org;/MailingLists/">
+<!ENTITY url-debian-lists-new "&url-debian-lists;HOWTO_start_list">
+<!ENTITY url-bts "http://&www-debian-org;/Bugs/">
+<!ENTITY url-bts-report "&url-bts;Reporting">
+<!ENTITY url-bts-devel "&url-bts;Developer">
+<!ENTITY url-bts-control "&url-bts;server-control">
+<!ENTITY url-debian-mirrors "http://&www-debian-org;/mirror/">
+<!ENTITY url-debian-mirroring "&url-debian-mirrors;">
+<!ENTITY url-debian-ports "http://&www-debian-org;/ports/">
+<!ENTITY url-debian-port-lists "http://&lists-host;/ports.html">
+<!ENTITY url-wnpp "http://&www-debian-org;/devel/wnpp/">
+<!ENTITY url-devel-docs "http://&www-debian-org;/devel/">
+<!ENTITY url-vote "http://&www-debian-org;/vote/">
+<!ENTITY url-cvsweb "http://cvs.debian.org/">
+<!ENTITY url-devel-machines "http://db.debian.org/machines.cgi">
+<!ENTITY url-buildd "http://buildd.debian.org/">
+<!ENTITY url-lintian "http://lintian.debian.org/">
+<!ENTITY url-debian-qa "http://qa.debian.org/">
+<!ENTITY url-debian-qa-orphaned "&url-debian-qa;orphaned.html">
+<!ENTITY url-debian-db "https://db.debian.org/">
+<!ENTITY url-debian-db-login "&url-debian-db;login.html">
+<!ENTITY url-debian-db-mail-gw "http://db.debian.org/doc-mail.html">
+<!ENTITY url-debian-db-doc "http://db.debian.org/doc-general.html">
+<!ENTITY url-newmaint "&url-devel-docs;join/newmaint">
+<!ENTITY url-newmaint-db "http://nm.debian.org/">
+<!ENTITY url-newmaint-advocate "&url-devel-docs;join/nm-advocate">
+<!ENTITY url-newmaint-amchecklist "&url-devel-docs;join/nm-amchecklist">
+<!ENTITY url-newmaint-apply "http://nm.debian.org/newnm.php">
+<!ENTITY url-newmaint-id "http://&www-debian-org;/devel/join/nm-step2">
+<!ENTITY url-newmaint-guide "http://&www-debian-org;/doc/maint-guide/">
+<!ENTITY url-gpg-coord "http://nm.debian.org/gpg.php">
+<!ENTITY url-debian-security-advisories "http://&www-debian-org;/security/">
+<!ENTITY url-tech-ctte "http://&www-debian-org;/devel/tech-ctte">
+<!ENTITY url-ddpo "http://qa.debian.org/developer.php">
+
+<!ENTITY url-debian-keyring "http://&ftp-debian-org;/debian/doc/debian-keyring.tar.gz">
+<!ENTITY url-readme-non-us "http://&ftp-debian-org;/debian/README.non-US">
+<!ENTITY url-incoming "http://incoming.debian.org/">
+<!ENTITY url-testing-maint "http://www.debian.org/devel/testing">
+<!-- deprecated -->
+<!ENTITY url-testing-faq "&url-testing-maint;">
+
+<!ENTITY us-upload-dir "<filename>/org/ftp.debian.org/incoming/</filename>">
+<!ENTITY non-us-upload-dir "<filename>/org/non-us.debian.org/incoming/</filename>">
+<!ENTITY url-chiark-readme "ftp://ftp.chiark.greenend.org.uk/pub/debian/private/project/README.how-to-upload">
+<!ENTITY url-upload-erlangen "ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue/">
+<!ENTITY url-upload-samosa "ftp://samosa.debian.org/pub/UploadQueue/">
+<!ENTITY url-upload-jp "ftp://master.debian.or.jp/pub/Incoming/upload/">
+
+<!ENTITY url-mentors "http://people.debian.org/~mpalmer/debian-mentors_FAQ.html">
+<!ENTITY url-sponsors "http://www.internatif.org/bortzmeyer/debian/sponsor/">
+
+<!ENTITY url-rules-files "http://arch.debian.org/arch/private/srivasta/">
+
+<!ENTITY url-debconf-l10n-help "http://&www-debian-org;/intl/l10n/templates/hints">
+
+<!ENTITY url-dmup "http://&www-debian-org;/devel/dmup">
+<!ENTITY url-worldmap "http://&www-debian-org;/devel/developers.loc">
+
+<!ENTITY url-i18n-doc-check "http://cvs.debian.org/boot-floppies/documentation/doc-check?rev=HEAD&content-type=text/vnd.viewcvs-markup">
+
+<!ENTITY url-eg-desc-upstream-info "http://&packages-host;/unstable/web/wml">
+
+<!ENTITY url-alioth "http://alioth.debian.org/">
+
+<!--
+ URLs, non-debian
+ -->
+<!ENTITY url-gnu-manifesto "http://www.gnu.org/gnu/manifesto.html">
+<!ENTITY url-gpl "http://www.gnu.org/copyleft/gpl.html">
+<!ENTITY url-pgp-faq "http://www.cam.ac.uk.pgp.net/pgpnet/pgp-faq/">
+<!ENTITY url-rfc2440 "http://www.rfc-editor.org/rfc/rfc2440.txt">
+<!ENTITY url-u.s.-export "http://www.bxa.doc.gov/Encryption/PubAvailEncSourceCodeNofify.html">
+<!ENTITY url-notification-of-export "http://www.bxa.doc.gov/Encryption/">
+<!ENTITY url-openprojects "http://www.freenode.net/">
+<!ENTITY url-oftc "http://www.oftc.net/oftc/">
+
+<!-- Debian email addresses -->
+<!ENTITY email-listmaster "<email>listmaster@&lists-host;</email>">
+<!ENTITY email-debian-announce "<email>debian-announce@&lists-host;</email>">
+<!ENTITY email-devel-ref "<email>developers-reference@&packages-host;</email>">
+<!ENTITY email-debian-changes "<email>debian-changes@lists.debian.org</email>">
+<!ENTITY email-debian-devel "<email>debian-devel@&lists-host;</email>">
+<!ENTITY email-debian-devel-announce "<email>debian-devel-announce@&lists-host;</email>">
+<!ENTITY email-debian-devel-changes "<email>debian-devel-changes@lists.debian.org</email>">
+<!ENTITY email-debian-devel-req "<email>debian-devel-REQUEST@&lists-host;</email>">
+<!ENTITY email-debian-i18n "<email>debian-i18n@&lists-host;</email>">
+<!ENTITY email-debian-mentors "<email>debian-mentors@&lists-host;</email>">
+<!ENTITY email-debian-private "<email>debian-private@&lists-host;</email>">
+<!ENTITY email-debian-project "<email>debian-project@&lists-host;</email>">
+<!ENTITY email-debian-policy "<email>debian-policy@&lists-host;</email>">
+<!ENTITY email-debian-user "<email>debian-user@&lists-host;</email>">
+<!ENTITY orphan-address "<packages@qa.debian.org>">
+<!ENTITY email-debian-qa "<email>debian-qa@&lists-host;</email>">
+<!ENTITY email-debian-release "<email>debian-release@&lists-host;</email>">
+<!ENTITY email-debian-email "<email>debian-email@&lists-host;</email>">
+<!ENTITY email-debian-vote "<email>debian-vote@&lists-host;</email>">
+<!ENTITY email-debian-security-announce "<email>debian-security-announce@&lists-host;</email>">
+<!ENTITY email-debian-l10n-english "<email>debian-l10n-english@&lists-host;</email>">
+<!ENTITY email-mia "<email>mia@qa.debian.org</email>">
+
+<!ENTITY email-new-maintainer "<email>new-maintainer@debian.org</email>">
+<!ENTITY email-debian-keyring "<email>keyring-maint@debian.org</email>">
+<!ENTITY email-debian-admin "<email>debian-admin@debian.org</email>">
+<!ENTITY email-ftpmaster "<email>ftpmaster@debian.org</email>">
+<!ENTITY email-override "<email>override-change@debian.org</email>">
+<!ENTITY email-wnpp "<email>wnpp@debian.org</email>">
+<!ENTITY email-bts-control "<email>control@&bugs-host;</email>">
+<!ENTITY email-security-team "<email>team@security.debian.org</email>">
+
+<!-- misc Debian info -->
+<!ENTITY file-mail-lists "<filename>/usr/share/doc/debian/mailing-lists.txt</filename>">
+<!ENTITY file-bts-docs "<filename>/usr/share/doc/debian/bug-*</filename>">
+<!ENTITY file-python-policy "<filename>/usr/share/doc/python/python-policy.txt.gz</filename>">
+<!ENTITY file-ocaml-policy "<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename>">
+<!ENTITY file-lisp-controller "<filename>/usr/share/doc/common-lisp-controller/README.packaging</filename>">
+<!ENTITY file-debian-private-archive "~debian/archive/debian-private/">
+<!ENTITY file-bpp-autotools "<filename>/usr/share/doc/autotools-dev/README.Debian.gz</filename>">
+
+<!ENTITY cron-bug-report '0 17 * * fri echo "index maint <replaceable>address</replaceable>" | mail request@&bugs-host;'>
+
+<!--
+ misc, non-debian
+ -->
+<!ENTITY pgp-keyserv "<literal>subkeys.pgp.net</literal>">
+
+<!ENTITY sample-dist-dirtree "<screen>dists/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>">
+
+<!ENTITY example-uu "<programlisting>uuencode-file:
+ perl -ne 'print(pack "u", $$_);' $(file) > $(file).uuencoded
+
+uudecode-file:
+ perl -ne 'print(unpack "u", $$_);' $(file).uuencoded > $(file)</programlisting>">
+
+<!ENTITY example-pathfind '<programlisting>pathfind() {
+ OLDIFS="$IFS"
+ IFS=:
+ for p in $PATH; do
+ if [ -x "$p/$*" ]; then
+ IFS="$OLDIFS"
+ return 0
+ fi
+ done
+ IFS="$OLDIFS"
+ return 1
+}</programlisting>'>
<?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="developer-duties">
<title>Debian Developer's Duties</title>
<section id="user-maint">
<title>Maintaining your Debian information</title>
<para>
There's a LDAP database containing information about Debian developers at
-<ulink url="https://db.debian.org/"></ulink>. You should enter your
+<ulink url="&url-debian-db;"></ulink>. You should enter your
information there and update it as it changes. Most notably, make sure that
the address where your debian.org email gets forwarded to is always up to date,
as well as the address where you get your debian-private subscription if you
<para>
If you add signatures to your public key, or add user identities, you can
update the Debian key ring by sending your key to the key server at
-<literal>keyring.debian.org</literal>.
+<literal>&keyserver-host;</literal>.
</para>
<para>
If you need to add a completely new key or remove an old key, you need to get
invalid, you also have to add the revocation certificate. If there is no real
reason for a new key, the Keyring Maintainers might reject the new key.
Details can be found at <ulink
-url="http://keyring.debian.org/replacing_keys.html"></ulink>.
+url="http://&keyserver-host;/replacing_keys.html"></ulink>.
</para>
<para>
The same key extraction routines discussed in <xref linkend="registering"/>
<para>
Even though Debian isn't really a democracy, we use a democratic process to
elect our leaders and to approve general resolutions. These procedures are
-defined by the <ulink url="http://www.debian.org/devel/constitution">Debian
+defined by the <ulink url="&url-constitution;">Debian
Constitution</ulink>.
</para>
<para>
Other than the yearly leader election, votes are not routinely held, and they
are not undertaken lightly. Each proposal is first discussed on the
-<email>debian-vote@lists.debian.org</email> mailing list and it requires
+<email>debian-vote@&lists-host;</email> mailing list and it requires
several endorsements before the project secretary starts the voting procedure.
</para>
<para>
You don't have to track the pre-vote discussions, as the secretary will issue
several calls for votes on
-<email>debian-devel-announce@lists.debian.org</email> (and all developers are
+<email>debian-devel-announce@&lists-host;</email> (and all developers are
expected to be subscribed to that list). Democracy doesn't work well if people
don't take part in the vote, which is why we encourage all developers to vote.
Voting is conducted via GPG-signed/encrypted email messages.
</para>
<para>
The list of all proposals (past and current) is available on the <ulink
-url="http://www.debian.org/vote/">Debian Voting Information</ulink> page, along
+url="&url-vote;">Debian Voting Information</ulink> page, along
with information on how to make, second and vote on proposals.
</para>
</section>
</para>
<para>
In order to inform the other developers, there are two things that you should
-do. First send a mail to <email>debian-private@lists.debian.org</email> with
+do. First send a mail to <email>debian-private@&lists-host;</email> with
[VAC] prepended to the subject of your message<footnote><para> This is so that
the message can be easily filtered by people who don't want to read vacation
notices. </para> </footnote> and state the period of time when you will be on
</para>
<para>
Ideally, you should sign up at the <ulink
-url="http://nm.debian.org/gpg.php">GPG coordination site</ulink> when booking a
+url="&url-newmaint-db;gpg.php">GPG coordination site</ulink> when booking a
holiday and check if anyone there is looking for signing. This is especially
important when people go to exotic places where we don't have any developers
yet but where there are people who are interested in applying.
corrected as quickly as possible.
</para>
<para>
-Developers who are part of the <ulink url="http://qa.debian.org/">Quality
+Developers who are part of the <ulink url="&url-debian-qa;">Quality
Assurance</ulink> group are following all such bugs, and trying to help
whenever possible. If, for any reason, you aren't able fix an RC bug in a
package of yours within 2 weeks, you should either ask for help by sending a
mail to the Quality Assurance (QA) group
-<email>debian-qa@lists.debian.org</email>, or explain your difficulties and
+<email>debian-qa@&lists-host;</email>, or explain your difficulties and
present a plan to fix them by sending a mail to the bug report. Otherwise,
people from the QA group may want to do a Non-Maintainer Upload (see <xref
linkend="nmu"/> ) after trying to contact you (they might not wait as long as
<listitem>
<para>
Send an gpg-signed email about why you are leaving the project to
-<email>debian-private@lists.debian.org</email>.
+<email>debian-private@&lists-host;</email>.
</para>
</listitem>
<listitem>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book 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;
+]>
<book lang="en">
<title>Debian Developer's Reference</title>
<bookinfo>
<author>
<othername>Developer's Reference Team</othername>
-<email>developers-reference@packages.debian.org</email>
+<email>developers-reference@&packages-host;</email>
</author>
<author>
<firstname>Andreas</firstname> <surname>Barth</surname>
</para>
<para>
A copy of the GNU General Public License is available as
-<filename>/usr/share/common-licenses/GPL</filename> in the Debian GNU/Linux
+&file-GPL; in the &debian-formal;
distribution or on the World Wide Web at <ulink
url="http://www.gnu.org/copyleft/gpl.html">the GNU web site</ulink>. You can
-also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin
-Street, Fifth Floor, Boston, MA 02110-1301, USA.
+also obtain it by writing to the &fsf-addr;.
</para>
<para>
If you want to print this reference, you should use the <ulink
<?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="l10n">
<title>Internationalizing, translating, being internationalized and being translated</title>
<para>
</para>
<para>
According to <ulink
-url="http://www.debian.org/doc/manuals/intro-i18n/">Introduction to
+url="http://&www-debian-org;/doc/manuals/intro-i18n/">Introduction to
i18n</ulink> from Tomohiro KUBOTA, I18N (internationalization) means
modification of a software or related technologies so that a software can
potentially handle multiple languages, customs, and so on in the world. while
url="http://developer.gnome.org/projects/gtp/">Gnome translation
Project</ulink> or the <ulink url="http://i18n.kde.org/">KDE one</ulink>. The
only centralized resource within Debian is the <ulink
-url="http://www.debian.org/intl/l10n/">Central Debian translation
+url="http://&www-debian-org;/intl/l10n/">Central Debian translation
statistics</ulink>, where you can find some statistics about the translation
files found in the actual packages, but no real infrastructure to ease the
translation process.
the work of translators, who could use the DDTP to do their work (but the
French and Brazilian teams don't). Some statistics can be found both on the
DDTP site (about what is actually translated), and on the <ulink
-url="http://www.debian.org/intl/l10n/">Central Debian translation
+url="http://&www-debian-org;/intl/l10n/">Central Debian translation
statistics</ulink> site (about what is integrated in the packages).
</para>
<para>
</para>
<para>
There is an effort to handle Debian-specific man pages within a <ulink
-url="http://cvs.debian.org/manpages/?cvsroot=debian-doc">specific CVS
+url="&url-cvsweb;manpages/?cvsroot=debian-doc">specific CVS
repository</ulink>.
</para>
</section>
<?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="new-maintainer">
<title>Applying to Become a Maintainer</title>
<section id="getting-started">
<title>Getting started</title>
<para>
So, you've read all the documentation, you've gone through the <ulink
-url="http://www.debian.org/doc/maint-guide/">Debian New Maintainers'
+url="http://&www-debian-org;/doc/maint-guide/">Debian New Maintainers'
Guide</ulink>, understand what everything in the <systemitem
role="package">hello</systemitem> example package is for, and you're about to
Debianize your favorite piece of software. How do you actually become a Debian
developer so that your work can be incorporated into the Project?
</para>
<para>
-Firstly, subscribe to <email>debian-devel@lists.debian.org</email> if you
+Firstly, subscribe to <email>debian-devel@&lists-host;</email> if you
haven't already. Send the word <literal>subscribe</literal> in the
<emphasis>Subject</emphasis> of an email to
-<email>debian-devel-REQUEST@lists.debian.org</email>. In case of problems,
-contact the list administrator at <email>listmaster@lists.debian.org</email>.
+<email>debian-devel-REQUEST@&lists-host;</email>. In case of problems,
+contact the list administrator at <email>listmaster@&lists-host;</email>.
More information on available mailing lists can be found in <xref
linkend="mailing-lists"/> .
-<email>debian-devel-announce@lists.debian.org</email> is another list which is
+<email>debian-devel-announce@&lists-host;</email> is another list which is
mandatory for anyone who wishes to follow Debian's development.
</para>
<para>
</para>
<para>
Another good list to subscribe to is
-<email>debian-mentors@lists.debian.org</email>. See <xref linkend="mentors"/>
+<email>debian-mentors@&lists-host;</email>. See <xref linkend="mentors"/>
for details. The IRC channel <literal>#debian</literal> can also be helpful;
see <xref linkend="irc-channels"/> .
</para>
<para>
-When you know how you want to contribute to Debian GNU/Linux, you should get in
+When you know how you want to contribute to &debian-formal;, you should get in
contact with existing Debian maintainers who are working on similar tasks.
That way, you can learn from experienced developers. For example, if you are
interested in packaging existing software for Debian, you should try to get a
sponsor. A sponsor will work together with you on your package and upload it
to the Debian archive once they are happy with the packaging work you have
done. You can find a sponsor by mailing the
-<email>debian-mentors@lists.debian.org</email> mailing list, describing your
+<email>debian-mentors@&lists-host;</email> mailing list, describing your
package and yourself and asking for a sponsor (see <xref linkend="sponsoring"/>
and <ulink
url="http://people.debian.org/~mpalmer/debian-mentors_FAQ.html"></ulink> for
<para>
One pitfall could be a too-generic local part in your mailadress: Terms like
mail, admin, root, master should be avoided, please see <ulink
-url="http://www.debian.org/MailingLists/"></ulink> for details.
+url="&url-debian-lists;"></ulink> for details.
</para>
</section>
<section id="mentors">
<title>Debian mentors and sponsors</title>
<para>
-The mailing list <email>debian-mentors@lists.debian.org</email> has been set up
+The mailing list <email>debian-mentors@&lists-host;</email> has been set up
for novice maintainers who seek help with initial packaging and other
developer-related issues. Every new developer is invited to subscribe to that
list (see <xref linkend="mailing-lists"/> for details).
<section id="registering">
<title>Registering as a Debian developer</title>
<para>
-Before you decide to register with Debian GNU/Linux, you will need to read all
+Before you decide to register with &debian-formal;, you will need to read all
the information available at the <ulink
-url="http://www.debian.org/devel/join/newmaint">New Maintainer's
+url="&url-newmaint;">New Maintainer's
Corner</ulink>. It describes in detail the preparations you have to do before
you can register to become a Debian developer. For example, before you apply,
-you have to read the <ulink url="http://www.debian.org/social_contract">Debian
+you have to read the <ulink url="&url-social-contract;">Debian
Social Contract</ulink>. Registering as a developer means that you agree with
and pledge to uphold the Debian Social Contract; it is very important that
-maintainers are in accord with the essential ideas behind Debian GNU/Linux.
+maintainers are in accord with the essential ideas behind &debian-formal;.
Reading the <ulink url="http://www.gnu.org/gnu/manifesto.html">GNU
Manifesto</ulink> would also be a good idea.
</para>
<para>
The process of registering as a developer is a process of verifying your
identity and intentions, and checking your technical skills. As the number of
-people working on Debian GNU/Linux has grown to over 900 and our systems are
+people working on &debian-formal; has grown to over &number-of-maintainers; and our systems are
used in several very important places, we have to be careful about being
compromised. Therefore, we need to verify new maintainers before we can give
them accounts on our servers and let them upload packages.
technical documentation. Furthermore, you need a GnuPG key which has been
signed by an existing Debian maintainer. If your GnuPG key is not signed yet,
you should try to meet a Debian Developer in person to get your key signed.
-There's a <ulink url="http://nm.debian.org/gpg.php">GnuPG Key Signing
+There's a <ulink url="&url-newmaint-db;gpg.php">GnuPG Key Signing
Coordination page</ulink> which should help you find a Debian Developer close
to you. (If there is no Debian Developer close to you, alternative ways to
pass the ID check may be permitted as an absolute exception on a
case-by-case-basis. See the <ulink
-url="http://www.debian.org/devel/join/nm-step2">identification page</ulink> for
+url="&url-devel-docs;join/nm-step2">identification page</ulink> for
more information.)
</para>
<para>
</para>
<para>
If your public key isn't on a public key server such as
-<literal>subkeys.pgp.net</literal>, please read the documentation available at
-<ulink url="http://www.debian.org/devel/join/nm-step2">NM Step 2:
+&pgp-keyserv;, please read the documentation available at
+<ulink url="&url-devel-docs;join/nm-step2">NM Step 2:
Identification</ulink>. That document contains instructions on how to put your
key on the public key servers. The New Maintainer Group will put your public
key on the servers if it isn't already there.
<para>
When you have found an advocate, have your GnuPG key signed and have already
contributed to Debian for a while, you're ready to apply. You can simply
-register on our <ulink url="http://nm.debian.org/newnm.php">application
+register on our <ulink url="&url-newmaint-db;newnm.php">application
page</ulink>. After you have signed up, your advocate has to confirm your
application. When your advocate has completed this step you will be assigned
an Application Manager who will go with you through the necessary steps of the
New Maintainer process. You can always check your status on the <ulink
-url="http://nm.debian.org/">applications status board</ulink>.
+url="&url-newmaint-db;">applications status board</ulink>.
</para>
<para>
For more details, please consult <ulink
-url="http://www.debian.org/devel/join/newmaint">New Maintainer's Corner</ulink>
+url="&url-newmaint;">New Maintainer's Corner</ulink>
at the Debian web site. Make sure that you are familiar with the necessary
steps of the New Maintainer process before actually applying. If you are well
prepared, you can save a lot of time later on.
<?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="pkgs">
<title>Managing Packages</title>
<para>
<title>New packages</title>
<para>
If you want to create a new package for the Debian distribution, you should
-first check the <ulink url="http://www.debian.org/devel/wnpp/">Work-Needing and
+first check the <ulink url="&url-wnpp;">Work-Needing and
Prospective Packages (WNPP)</ulink> list. Checking the WNPP list ensures that
no one is already working on packaging that software, and that effort is not
-duplicated. Read the <ulink url="http://www.debian.org/devel/wnpp/">WNPP web
+duplicated. Read the <ulink url="&url-wnpp;">WNPP web
pages</ulink> for more information.
</para>
<para>
-- <replaceable>short description</replaceable>'', substituting the name of the
new package for <replaceable>foo</replaceable>. The severity of the bug report
must be set to <emphasis>wishlist</emphasis>. If you feel it's necessary, send
-a copy to <email>debian-devel@lists.debian.org</email> by putting the address
+a copy to <email>debian-devel@&lists-host;</email> by putting the address
in the <literal>X-Debbugs-CC:</literal> header of the message (no, don't use
<literal>CC:</literal>, because that way the message's subject won't indicate
the bug number).
</listitem>
</itemizedlist>
<para>
-Please see <ulink url="http://ftp-master.debian.org/REJECT-FAQ.html"></ulink>
+Please see <ulink url="http://&ftp-master-host;/REJECT-FAQ.html"></ulink>
for common rejection reasons for a new package.
</para>
</section>
</para>
<para>
The Release Team (which can be reached at
-<email>debian-release@lists.debian.org</email>) will regularly evaluate the
+<email>debian-release@&lists-host;</email>) will regularly evaluate the
uploads To <emphasis>stable-proposed-updates</emphasis> and decide if your
package can be included in <emphasis>stable</emphasis>. Please be clear (and
verbose, if necessary) in your changelog entries for uploads to
<title>Uploading to <literal>ftp-master</literal></title>
<para>
To upload a package, you should upload the files (including the signed changes
-and dsc-file) with anonymous ftp to <literal>ftp-master.debian.org</literal> in
+and dsc-file) with anonymous ftp to <literal>&ftp-master-host;</literal> in
the directory <ulink
-url="ftp://ftp-master.debian.org/pub/UploadQueue/">/pub/UploadQueue/</ulink>.
+url="ftp://&ftp-master-host;&upload-queue;">&upload-queue;</ulink>.
To get the files processed there, they need to be signed with a key in the
debian keyring.
</para>
To alter the actual section that a package is put in, you need to first make
sure that the <filename>debian/control</filename> file in your package is
accurate. Next, send an email <email>override-change@debian.org</email> or
-submit a bug against <systemitem role="package">ftp.debian.org</systemitem>
+submit a bug against <systemitem role="package">&ftp-debian-org;</systemitem>
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.
</para>
For more information about <emphasis>override files</emphasis>, see
<citerefentry> <refentrytitle>dpkg-scanpackages</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> and <ulink
-url="http://www.debian.org/Bugs/Developer#maintincorrect"></ulink>.
+url="&url-bts-devel;#maintincorrect"></ulink>.
</para>
<para>
Note that the <literal>Section</literal> field describes both the section as
well as the subsection, which are described in <xref
linkend="archive-sections"/> . If the section is main, it should be omitted.
The list of allowable subsections can be found in <ulink
-url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections"></ulink>.
+url="&url-debian-policy;ch-archive.html#s-subsections"></ulink>.
</para>
</section>
<title>Handling bugs</title>
<para>
Every developer has to be able to work with the Debian <ulink
-url="http://www.debian.org/Bugs/">bug tracking system</ulink>. This includes
+url="&url-bts;">bug tracking system</ulink>. This includes
knowing how to file bug reports properly (see <xref linkend="submit-bug"/> ),
how to update them and reorder them, and how to process and close them.
</para>
<para>
The bug tracking system's features are described in the <ulink
-url="http://www.debian.org/Bugs/Developer">BTS documentation for
+url="&url-bts-devel;">BTS documentation for
developers</ulink>. This includes closing bugs, sending followup messages,
assigning severities and tags, marking bugs as forwarded, and other issues.
</para>
reports about the same issue, or reopening bugs when they are prematurely
closed, are handled using the so-called control mail server. All of the
commands available on this server are described in the <ulink
-url="http://www.debian.org/Bugs/server-control">BTS control server
+url="&url-bts-control;">BTS control server
documentation</ulink>.
</para>
<section id="bug-monitoring">
<title>Monitoring bugs</title>
<para>
If you want to be a good maintainer, you should periodically check the <ulink
-url="http://www.debian.org/Bugs/">Debian bug tracking system (BTS)</ulink> for
+url="&url-bts;">Debian bug tracking system (BTS)</ulink> for
your packages. The BTS contains all the open bugs against your packages. You
can check them by browsing this page:
-<literal>http://bugs.debian.org/<replaceable>yourlogin</replaceable>@debian.org</literal>.
+<literal>http://&bugs-host;/<replaceable>yourlogin</replaceable>@debian.org</literal>.
</para>
<para>
Maintainers interact with the BTS via email addresses at
-<literal>bugs.debian.org</literal>. Documentation on available commands can be
-found at <ulink url="http://www.debian.org/Bugs/"></ulink>, or, if you have
+<literal>&bugs-host;</literal>. Documentation on available commands can be
+found at <ulink url="&url-bts;"></ulink>, or, if you have
installed the <systemitem role="package">doc-debian</systemitem> package, you
can look at the local files <filename>/usr/share/doc/debian/bug-*</filename>.
</para>
</para>
<screen>
# ask for weekly reports of bugs in my packages
-0 17 * * fri echo index maint <replaceable>address</replaceable> | mail request@bugs.debian.org
+&cron-bug-report;
</screen>
<para>
Replace <replaceable>address</replaceable> with your official Debian maintainer
<para>
When responding to bugs, make sure that any discussion you have about bugs is
sent both to the original submitter of the bug, and to the bug itself (e.g.,
-<email>123@bugs.debian.org</email>). If you're writing a new mail and you
+<email>123@&bugs-host;</email>). If you're writing a new mail and you
don't remember the submitter email address, you can use the
-<email>123-submitter@bugs.debian.org</email> email to contact the submitter
+<email>123-submitter@&bugs-host;</email> email to contact the submitter
<emphasis>and</emphasis> to record your mail within the bug log (that means you
-don't need to send a copy of the mail to <email>123@bugs.debian.org</email>).
+don't need to send a copy of the mail to <email>123@&bugs-host;</email>).
</para>
<para>
If you get a bug which mentions FTBFS, this means Fails to build from source.
<para>
Once you've dealt with a bug report (e.g. fixed it), mark it as
<emphasis>done</emphasis> (close it) by sending an explanation message to
-<email>123-done@bugs.debian.org</email>. If you're fixing a bug by changing
+<email>123-done@&bugs-host;</email>. If you're fixing a bug by changing
and uploading the package, you can automate bug closing as described in <xref
linkend="upload-bugfix"/> .
</para>
<para>
You should <emphasis>never</emphasis> close bugs via the bug server
<literal>close</literal> command sent to
-<email>control@bugs.debian.org</email>. If you do so, the original submitter
+<email>control@&bugs-host;</email>. If you do so, the original submitter
will not receive any information about why the bug was closed.
</para>
</section>
As a package maintainer, you will often find bugs in other packages or have
bugs reported against your packages which are actually bugs in other packages.
The bug tracking system's features are described in the <ulink
-url="http://www.debian.org/Bugs/Developer">BTS documentation for Debian
+url="&url-bts-devel;">BTS documentation for Debian
developers</ulink>. Operations such as reassigning, merging, and tagging bug
reports are described in the <ulink
-url="http://www.debian.org/Bugs/server-control">BTS control server
+url="&url-bts-control;">BTS control server
documentation</ulink>. This section contains some guidelines for managing your
own bugs, based on the collective Debian developer experience.
</para>
technical committee by reassigning the bug to <systemitem
role="package">tech-ctte</systemitem> (you may use the clone command of the BTS
if you wish to keep it reported against your package). Before doing so, please
-read the <ulink url="http://www.debian.org/devel/tech-ctte">recommended
+read the <ulink url="&url-devel-docs;tech-ctte">recommended
procedure</ulink>.
</para>
</listitem>
If the bug is real but it's caused by another package, just reassign the bug to
the right package. If you don't know which package it should be reassigned to,
you should ask for help on <link linkend="irc-channels">IRC</link> or
-on <email>debian-devel@lists.debian.org</email>. Please make sure that the
+on <email>debian-devel@&lists-host;</email>. Please make sure that the
maintainer(s) of the package the bug is reassigned to know why you reassigned
it.
</para>
<para>
If the bug is related to the packaging, you just fix it. If you are not able
to fix it yourself, then tag the bug as <literal>help</literal>. You can also
-ask for help on <email>debian-devel@lists.debian.org</email> or
-<email>debian-qa@lists.debian.org</email>. If it's an upstream problem, you
+ask for help on <email>debian-devel@&lists-host;</email> or
+<email>debian-qa@&lists-host;</email>. If it's an upstream problem, you
have to forward it to the upstream author. Forwarding a bug is not enough, you
have to check at each release if the bug has been fixed or not. If it has, you
just close it, otherwise you have to remind the author about it. If you have
close the bugs for you. For example:
</para>
<screen>
--cannon (3.1415) unstable; urgency=low
+acme-cannon (3.1415) unstable; urgency=low
* Frobbed with options (closes: Bug#98339)
* Added safety to prevent operator dismemberment, closes: bug#98765,
don't hesitate to undo any damage the error caused. To reopen wrongly closed
bugs, send a <literal>reopen <replaceable>XXX</replaceable></literal> command
to the bug tracking system's control address,
-<email>control@bugs.debian.org</email>. To close any remaining bugs that were
+<email>control@&bugs-host;</email>. To close any remaining bugs that were
fixed by your upload, email the <filename>.changes</filename> file to
-<email>XXX-done@bugs.debian.org</email>, where <replaceable>XXX</replaceable>
+<email>XXX-done@&bugs-host;</email>, where <replaceable>XXX</replaceable>
is the bug number, and put Version: YYY and an empty line as the first two
lines of the body of the email, where <replaceable>YYY</replaceable> is the
first version where the bug has been fixed.
Bear in mind that it is not obligatory to close bugs using the changelog as
described above. If you simply want to close bugs that don't have anything to
do with an upload you made, do it by emailing an explanation to
-<email>XXX-done@bugs.debian.org</email>. Do <emphasis
+<email>XXX-done@&bugs-host;</email>. Do <emphasis
role="strong">not</emphasis> close bugs in the changelog entry of a version if
the changes in that version of the package don't have any bearing on the bug.
</para>
Security advisories are only issued for the current, released stable
distribution, and <emphasis>not</emphasis> for testing or unstable. When
released, advisories are sent to the
-<email>debian-security-announce@lists.debian.org</email> mailing list and
-posted on <ulink url="http://www.debian.org/security/">the security web
+<email>debian-security-announce@&lists-host;</email> mailing list and
+posted on <ulink url="http://&www-debian-org;/security/">the security web
page</ulink>. Security advisories are written and posted by the security team.
However they certainly do not mind if a maintainer can supply some of the
information for them, or write part of the text. Information that should be in
Sometimes a package will change its section. For instance, a package from the
`non-free' section might be GPL'd in a later version, in which case the package
should be moved to `main' or `contrib'.<footnote><para> See the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for
+url="&url-debian-policy;">Debian Policy Manual</ulink> for
guidelines on what section a package belongs in. </para> </footnote>
</para>
<para>
If you need to change the section for one of your packages, change the package
control information to place the package in the desired section, and re-upload
the package (see the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for
+url="&url-debian-policy;">Debian Policy Manual</ulink> for
details). You must ensure that you include the
<filename>.orig.tar.gz</filename> in your upload (even if you are not uploading
a new upstream version), or it will not appear in the new section together with
<para>
If for some reason you want to completely remove a package (say, if it is an
old compatibility library which is no longer required), you need to file a bug
-against <literal>ftp.debian.org</literal> asking that the package be removed;
+against <literal>&ftp-debian-org;</literal> asking that the package be removed;
as all bugs, this bug should normally have normal severity. Make sure you
indicate which distribution the package should be removed from. Normally, you
can only have packages removed from <emphasis>unstable</emphasis> and
<para>
Further information relating to these and other package removal related topics
may be found at <ulink url="http://wiki.debian.org/ftpmaster_Removals"></ulink>
-and <ulink url="http://qa.debian.org/howto-remove.html"></ulink>.
+and <ulink url="&url-debian-qa;howto-remove.html"></ulink>.
</para>
<para>
If in doubt concerning whether a package is disposable, email
-<email>debian-devel@lists.debian.org</email> asking for opinions. Also of
+<email>debian-devel@&lists-host;</email> asking for opinions. Also of
interest is the <command>apt-cache</command> program from the <systemitem
role="package">apt</systemitem> package. When invoked as <literal>apt-cache
showpkg <replaceable>package</replaceable></literal>, the program will show
details for <replaceable>package</replaceable>, including reverse depends.
Other useful programs include <literal>apt-cache rdepends</literal>,
<command>apt-rdepends</command> and <command>grep-dctrl</command>. Removal of
-orphaned packages is discussed on <email>debian-qa@lists.debian.org</email>.
+orphaned packages is discussed on <email>debian-qa@&lists-host;</email>.
</para>
<para>
Once the package has been removed, the package's bugs should be handled. They
When you make a mistake naming your package, you should follow a two-step
process to rename it. First, set your <filename>debian/control</filename> file
to replace and conflict with the obsolete name of the package (see the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink> for
+url="&url-debian-policy;">Debian Policy Manual</ulink> for
details). Once you've uploaded the package and the package has moved into the
-archive, file a bug against <literal>ftp.debian.org</literal> asking to remove
+archive, file a bug against <literal>&ftp-debian-org;</literal> asking to remove
the package with the obsolete name. Do not forget to properly reassign the
package's bugs at the same time.
</para>
<para>
If you can no longer maintain a package, you need to inform others, and see
that the package is marked as orphaned. You should set the package maintainer
-to <literal>Debian QA Group <packages@qa.debian.org></literal> and submit
+to <literal>Debian QA Group <&pts-host;></literal> and submit
a bug report against the pseudo package <systemitem
role="package">wnpp</systemitem>. The bug report should be titled <literal>O:
<replaceable>package</replaceable> -- <replaceable>short
orphaned. The severity of the bug should be set to
<emphasis>normal</emphasis>; if the package has a priority of standard or
higher, it should be set to important. If you feel it's necessary, send a copy
-to <email>debian-devel@lists.debian.org</email> by putting the address in the
+to <email>debian-devel@&lists-host;</email> by putting the address in the
X-Debbugs-CC: header of the message (no, don't use CC:, because that way the
message's subject won't indicate the bug number).
</para>
<emphasis>Request For Adoption</emphasis>.
</para>
<para>
-More information is on the <ulink url="http://www.debian.org/devel/wnpp/">WNPP
+More information is on the <ulink url="&url-wnpp;">WNPP
web pages</ulink>.
</para>
</section>
<title>Adopting a package</title>
<para>
A list of packages in need of a new maintainer is available in the <ulink
-url="http://www.debian.org/devel/wnpp/">Work-Needing and Prospective Packages
+url="&url-wnpp;">Work-Needing and Prospective Packages
list (WNPP)</ulink>. If you wish to take over maintenance of any of the
packages listed in the WNPP, please take a look at the aforementioned page for
information and procedures.
mailing list. If the discussion doesn't end with a positive conclusion, and
the issue is of a technical nature, consider bringing it to the attention of
the technical committee (see the <ulink
-url="http://www.debian.org/devel/tech-ctte">technical committee web
+url="&url-devel-docs;tech-ctte">technical committee web
page</ulink> for more information).
</para>
<para>
package. It is a unique and essential activity. In fact, porters do most of
the actual compiling of Debian packages. For instance, for a single
<emphasis>i386</emphasis> binary package, there must be a recompile for each
-architecture, which amounts to 12 more builds.
+architecture, which amounts to &number-of-arches; more builds.
</para>
<section id="kind-to-porters">
<title>Being kind to porters</title>
assistance (see <xref linkend="dpkg-depcheck"/> ).
</para>
<para>
-See the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+See the <ulink url="&url-debian-policy;">Debian Policy
Manual</ulink> for instructions on setting build dependencies.
</para>
</listitem>
<para>
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 <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+in the <ulink url="&url-debian-policy;">Debian Policy
Manual</ulink>. Setting your architecture to ``i386'' is usually incorrect.
</para>
</listitem>
<title>Mailing lists and web pages</title>
<para>
Web pages containing the status of each port can be found at <ulink
-url="http://www.debian.org/ports/"></ulink>.
+url="&url-debian-ports;"></ulink>.
</para>
<para>
Each port of Debian has a mailing list. The list of porting mailing lists can
-be found at <ulink url="http://lists.debian.org/ports.html"></ulink>. These
+be found at <ulink url="&url-debian-port-lists;"></ulink>. These
lists are used to coordinate porters, and to connect the users of a given port
with the porters.
</para>
<para>
Some of the data produced by <systemitem role="package">buildd</systemitem>
which is generally useful to porters is available on the web at <ulink
-url="http://buildd.debian.org/"></ulink>. This data includes nightly updated
+url="&url-buildd;"></ulink>. This data includes nightly updated
information from <command>andrea</command> (source dependencies) and
<systemitem role="package">quinn-diff</systemitem> (packages needing
recompilation).
it must be included in <filename>packages-arch-specific</filename>, a list used
by the <command>wanna-build</command> script. The current version is available
as <ulink
-url="http://cvs.debian.org/srcdep/Packages-arch-specific?cvsroot=dak"></ulink>;
+url="&url-cvsweb;srcdep/Packages-arch-specific?cvsroot=dak"></ulink>;
please see the top of the file for whom to contact for changes.
</para>
</listitem>
accidently upload it without noticing it doesn't work. If in the past some
binary packages were uploaded on unsupported architectures, request their
removal by filing a bug against <systemitem
-role="package">ftp.debian.org</systemitem>
+role="package">&ftp-debian-org;</systemitem>
</para>
</section>
Unless you know the maintainer is still active, it is wise to check the package
to see if it has been orphaned. The current list of orphaned packages which
haven't had their maintainer set correctly is available at <ulink
-url="http://qa.debian.org/orphaned.html"></ulink>. If you perform an NMU on an
+url="&url-debian-qa-orphaned;"></ulink>. If you perform an NMU on an
improperly orphaned package, please set the maintainer to ``Debian QA Group
-<packages@qa.debian.org>''.
+<&pts-host;>''.
</para>
</section>
<filename>debian/control</filename> file.
</para>
<screen>
-: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>
+Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>
</screen>
</listitem>
<listitem>
<para>
To find out whether a package is progressing into testing or not, see the
testing script output on the <ulink
-url="http://www.debian.org/devel/testing">web page of the testing
+url="&url-devel-docs;testing">web page of the testing
distribution</ulink>, or use the program <command>grep-excuses</command> which
is in the <systemitem role="package">devscripts</systemitem> package. This
utility can easily be used in a <citerefentry>
The <filename>update_excuses</filename> file does not always give the precise
reason why the package is refused; you may have to find it on your own by
looking for what would break with the inclusion of the package. The <ulink
-url="http://www.debian.org/devel/testing">testing web page</ulink> gives some
+url="&url-devel-docs;testing">testing web page</ulink> gives some
more information about the usual problems which may be causing such troubles.
</para>
<para>
</para>
<para>
Currently, this requires some manual hinting from the release team. Please
-contact them by sending mail to <email>debian-release@lists.debian.org</email>
+contact them by sending mail to <email>debian-release@&lists-host;</email>
if this happens to one of your packages.
</para>
</section>
</para>
<para>
If you want to see more details, you can look it up on
-merkel:/org/ftp.debian.org/testing/update_out/ (or there in
+merkel:/org/&ftp-debian-org;/testing/update_out/ (or there in
~aba/testing/update_out to see a setup with a smaller packages file). Via web,
it's at <ulink
-url="http://ftp-master.debian.org/testing/update_out_code/"></ulink>
+url="http://&ftp-master-host;/testing/update_out_code/"></ulink>
</para>
<para>
The hints are available via <ulink
-url="http://ftp-master.debian.org/testing/hints/"></ulink>.
+url="http://&ftp-master-host;/testing/hints/"></ulink>.
</para>
</section>
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 managers' eyes, you should read the instructions that they regularly
-give on <email>debian-devel-announce@lists.debian.org</email>.
+give on <email>debian-devel-announce@&lists-host;</email>.
</para>
<para>
You should not upload to <emphasis>testing-proposed-updates</emphasis> when you
<listitem>
<para>
After uploading and successful build on all platforms, contact the release team
-at <email>debian-release@lists.debian.org</email> and ask them to approve your
+at <email>debian-release@&lists-host;</email> and ask them to approve your
upload.
</para>
</listitem>
<?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>
<?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="scope">
<title>Scope of This Document</title>
<para>
of Debian packages nor how to generate them. Nor does this reference detail
the standards to which Debian software must comply. All of such information
can be found in the <ulink
-url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink>.
+url="&url-debian-policy;">Debian Policy Manual</ulink>.
</para>
<para>
Furthermore, this document is <emphasis>not an expression of formal
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE appendix 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;
+]>
<appendix id="tools">
<title>Overview of Debian Maintainer Tools</title>
<para>
</para>
<para>
You can also see a summary of all problems reported by Lintian on your packages
-at <ulink url="http://lintian.debian.org/"></ulink>. These reports contain the
+at <ulink url="&url-lintian;"></ulink>. These reports contain the
latest <command>lintian</command> output for the whole development distribution
(unstable).
</para>
You can run it over a pair of binary packages:
</para>
<screen>
- package_1-1_arch.deb package_2-1_arch.deb
+debdiff package_1-1_arch.deb package_2-1_arch.deb
</screen>
<para>
Or even a pair of changes files:
</para>
<screen>
- package_1-1_arch.changes package_2-1_arch.changes
+debdiff package_1-1_arch.changes package_2-1_arch.changes
</screen>
<para>
For more information please see <citerefentry>
part of a networked, distributed build environment. As the latter, it is part
of the system used by porters to build binary packages for all the available
architectures. See <xref linkend="buildd"/> for more information, and <ulink
-url="http://buildd.debian.org/"></ulink> to see the system in action.
+url="&url-buildd;"></ulink> to see the system in action.
</para>
</section>
first approximation of the build-dependencies. For example:
</para>
<screen>
--depcheck -b debian/rules build
+dpkg-depcheck -b debian/rules build
</screen>
<para>
<command>dpkg-depcheck</command> can also be used to check for run-time