chiark / gitweb /
First files for developers-reference in DocBook XML
authordebacle <debacle@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Tue, 26 Jun 2007 17:46:56 +0000 (17:46 +0000)
committerdebacle <debacle@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Tue, 26 Jun 2007 17:46:56 +0000 (17:46 +0000)
plus translation file using po4a.

git-svn-id: svn://anonscm.debian.org/ddp/developers-reference/trunk@4902 313b444b-1b9f-4f58-a734-7bb04f332e8d

52 files changed:
Makefile [new file with mode: 0644]
README-contrib [new file with mode: 0644]
best-pkging-practices.dbk [new file with mode: 0644]
beyond-pkging.dbk [new file with mode: 0644]
debian/TODO [new file with mode: 0644]
debian/changelog [new file with mode: 0644]
debian/compat [new file with mode: 0644]
debian/control [new file with mode: 0644]
debian/copyright [new file with mode: 0644]
debian/developers-reference-fr.doc-base [new file with mode: 0644]
debian/developers-reference-ja.doc-base [new file with mode: 0644]
debian/developers-reference.doc-base [new file with mode: 0644]
debian/rules [new file with mode: 0755]
debian/tocsubstvars [new file with mode: 0755]
developer-duties.dbk [new file with mode: 0644]
index.dbk [new file with mode: 0644]
l10n.dbk [new file with mode: 0644]
new-maintainer.dbk [new file with mode: 0644]
pkgs.dbk [new file with mode: 0644]
po4a/fr/best-pkging-practices.po [new file with mode: 0644]
po4a/fr/beyond-pkging.po [new file with mode: 0644]
po4a/fr/developer-duties.po [new file with mode: 0644]
po4a/fr/index.po [new file with mode: 0644]
po4a/fr/l10n.po [new file with mode: 0644]
po4a/fr/new-maintainer.po [new file with mode: 0644]
po4a/fr/pkgs.po [new file with mode: 0644]
po4a/fr/resources.po [new file with mode: 0644]
po4a/fr/scope.po [new file with mode: 0644]
po4a/fr/tools.po [new file with mode: 0644]
po4a/ja/best-pkging-practices.po [new file with mode: 0644]
po4a/ja/beyond-pkging.po [new file with mode: 0644]
po4a/ja/developer-duties.po [new file with mode: 0644]
po4a/ja/index.po [new file with mode: 0644]
po4a/ja/l10n.po [new file with mode: 0644]
po4a/ja/new-maintainer.po [new file with mode: 0644]
po4a/ja/pkgs.po [new file with mode: 0644]
po4a/ja/resources.po [new file with mode: 0644]
po4a/ja/scope.po [new file with mode: 0644]
po4a/ja/tools.po [new file with mode: 0644]
po4a/po/best-pkging-practices.pot [new file with mode: 0644]
po4a/po/beyond-pkging.pot [new file with mode: 0644]
po4a/po/developer-duties.pot [new file with mode: 0644]
po4a/po/index.pot [new file with mode: 0644]
po4a/po/l10n.pot [new file with mode: 0644]
po4a/po/new-maintainer.pot [new file with mode: 0644]
po4a/po/pkgs.pot [new file with mode: 0644]
po4a/po/resources.pot [new file with mode: 0644]
po4a/po/scope.pot [new file with mode: 0644]
po4a/po/tools.pot [new file with mode: 0644]
resources.dbk [new file with mode: 0644]
scope.dbk [new file with mode: 0644]
tools.dbk [new file with mode: 0644]

diff --git a/Makefile b/Makefile
new file mode 100644 (file)
index 0000000..c3f5a82
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,133 @@
+# Makefile, used for the DDP manuals.sgml area
+
+MANUAL         := $(notdir $(shell pwd))
+PUBLISHDIR     := /org/www.debian.org/www/doc/manuals
+
+SOURCES                := $(wildcard *.sgml)
+
+LANGS           := fr
+TARGETS                := $(foreach fmt,html txt pdf,developers-reference.$(fmt)) \
+                    $(foreach langext,$(LANGS), \
+                      $(foreach fmt,html txt pdf,developers-reference.$(langext).$(fmt)))
+
+# programs for creating output
+DEBIANDOC2HTML := debiandoc2html -c
+DEBIANDOC2TEXT := debiandoc2text
+DEBIANDOC2LATEX        := debiandoc2latex
+DEBIANDOC2PS   := debiandoc2latexps
+DEBIANDOC2PDF  := debiandoc2latexpdf
+
+htmllink       := echo "<!entity % htmltext \"INCLUDE\">" > dynamic.ent
+nohtmllink     := echo "<!entity % htmltext \"IGNORE\">" > dynamic.ent
+
+make_directory := install -d -m 755
+install_file   := install -m 644 -p
+
+MAX_TEX_RECURSION := 5
+
+.PHONY:        all dropold
+all:    $(TARGETS) dropold
+
+dropold:
+       -rm -rf developers-reference.ja.html
+
+
+.PHONY: validate
+validate:      $(addsuffix .validate,$(SOURCES))
+
+# hmmm, this rule may need to be revised/tested
+.PHONY: publish
+publish:       all
+       [ -d $(PUBLISHDIR) ] || exit 1
+       rm -f $(PUBLISHDIR)/$(MANUAL)/*.html
+       $(make_directory) $(PUBLISHDIR)/$(MANUAL)
+       $(install_file) developers-reference*.html/*.html developers-reference*pdf      \
+          $(PUBLISHDIR)/$(MANUAL)
+       ln -sf index.en.html $(PUBLISHDIR)/$(MANUAL)/index.html
+       ln -sf developers-reference.pdf $(PUBLISHDIR)/$(MANUAL)/developers-reference.en.pdf
+
+developers-reference.html:     developers-reference.sgml
+       $(htmllink)
+       $(DEBIANDOC2HTML) -l en $<
+
+developers-reference.html/*:   developers-reference.html
+
+developers-reference.%.html:   developers-reference.%.sgml
+       $(htmllink)
+       $(DEBIANDOC2HTML) -l $* $<
+
+developers-reference.txt:      developers-reference.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2TEXT) -l en -O $< > $@
+
+developers-reference.%.txt:    developers-reference.%.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2TEXT) -l $* -O $< > $@
+
+developers-reference.tex:      developers-reference.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2LATEX) -l en -O $< > $@
+
+developers-reference.%.tex:    developers-reference.%.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2LATEX) -l $* -O $< > $@
+
+developers-reference.ps:        developers-reference.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2PS) -l en $<
+
+developers-reference.%.ps:      developers-reference.%.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2PS) -l $* $<
+
+developers-reference.pdf:       developers-reference.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2PDF) -l en $<
+
+developers-reference.%.pdf:     developers-reference.%.sgml
+       $(nohtmllink)
+       $(DEBIANDOC2PDF) -l $* $<
+
+version.ent:   debian/changelog
+       ./debian/rules $@
+
+%.validate : % version.ent
+       nsgmls -wall -gues $<
+       touch $@
+
+USERMAP        := ../../ddp/CVSROOT/users
+.PHONY: prepare
+prepare:       ChangeLog
+       cvs ci -m "update for next release" ChangeLog
+
+.PHONY: ChangeLog
+ChangeLog:
+       @[ -f CVS/Root -a -f $(USERMAP) ] || \
+               ( echo "usermap file '$(USERMAP)' not found" 1>&2; exit 1 )
+       cvs2cl -r --usermap $(USERMAP)
+
+.PHONY: clean
+clean:
+       rm -rf developers-reference*.html
+       rm -f developers-reference*.txt developers-reference*.pdf \
+             developers-reference*.ps developers-reference*.lout* lout.li \
+             developers-reference*.sasp* developers-reference*.tex \
+             developers-reference*.aux developers-reference*.toc \
+             developers-reference*.idx developers-reference*.log \
+             developers-reference*.out developers-reference*.dvi \
+             developers-reference*.tpt
+       rm -f version.ent
+       rm -f `find . -name "*~" -o -name "*.bak"`
+       rm -f *.validate
+       rm -f *~ *.bak .#* core
+
+.PHONY: distclean
+distclean: clean
+       rm -f *.rej *.orig
+
+developers-reference$(SRCEXT).sgml: version.ent common.ent
+
+html: $(MANUAL).html
+
+# if rule bomb out, delete the target
+.DELETE_ON_ERROR:
diff --git a/README-contrib b/README-contrib
new file mode 100644 (file)
index 0000000..226b5a9
--- /dev/null
@@ -0,0 +1,71 @@
+* Useful Makefile targets
+
+The following 'make' targets exist for your convenience:
+
+  make validate
+        validate the well-formedness of all SGML materials
+
+  make all
+        build all languages in all formats
+
+  make developers-reference.sgml.validate
+        validate the well-formedness of the English manual
+
+  make developers-reference.html
+        build the English manual
+
+
+* Contacting
+
+To contain the maintainers of this package, email
+<developers-reference@packages.debian.org>.
+
+
+* Contributing
+
+If you want to contribute to the Developer's Reference, it's best to
+first submit a few patches as bug reports.  Writing patches for
+existing bugs are also always appreciated.  You may wish to make
+patches against the CVS sources, about which see below.
+
+Do not commit patches to the developers reference yourself unless
+authorized to do so. Patches need to be finalized and common opinion
+before they are applied. This is even true if you happen to have
+cvs access for other reasons.
+
+
+* CVS
+
+If you're interested in ongoing maintenance, once you've shown that
+you've mastered the style of the manual with a couple accepted
+patches, you can be given CVS pserver access. If you have already
+access to the CVS server for other reasons, do not use it unless
+authorized to do so.
+
+Instructions on how to get the CVS version of this software, including
+how to get CVS access, can be found at
+<URL:http://www.debian.org/doc/cvs>.
+
+
+* Translators
+
+We have tried to keep language-independant bits of text in common.ent.
+Feel free to truck stuff out of the English manual into common.ent if
+it's useful, or else report the problem.
+
+You should exploit CVS to see the diffs between when the document was
+last translated and the latest version.  Be sure to set the cvs-en-rev
+entity as appropriate when you do update a translation.
+
+We have provided commands to help with this.  To see the difference in
+numbers between the latest translated version and the latest version,
+do, for instance:
+
+  ./translation-status fr
+
+To get the diff between the latest translated version and the latest
+version:
+
+  ./translation-status -d fr
+
+
diff --git a/best-pkging-practices.dbk b/best-pkging-practices.dbk
new file mode 100644 (file)
index 0000000..f1130c2
--- /dev/null
@@ -0,0 +1,1750 @@
+<?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">
+<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
+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
+talented people have created great tools, tools which help you, the Debian
+maintainer, create and maintain excellent packages.
+</para>
+<para>
+This chapter provides some best practices for Debian developers.  All
+recommendations are merely that, and are not requirements or policy.  These are
+just some subjective hints, advice and pointers collected from Debian
+developers.  Feel free to pick and choose whatever works best for you.
+</para>
+<section id="bpp-debian-rules">
+<title>Best practices for <filename>debian/rules</filename></title>
+<para>
+The following recommendations apply to the <filename>debian/rules</filename>
+file.  Since <filename>debian/rules</filename> controls the build process and
+selects the files which go into the package (directly or indirectly), it's
+usually the file maintainers spend the most time on.
+</para>
+<section id="helper-scripts">
+<title>Helper scripts</title>
+<para>
+The rationale for using helper scripts in <filename>debian/rules</filename> is
+that they let maintainers use and share common logic among many packages.  Take
+for instance the question of installing menu entries: you need to put the file
+into <filename>/usr/lib/menu</filename> (or <filename>/usr/lib/menu</filename>
+for executable binary menufiles, if this is needed), and add commands to the
+maintainer scripts to register and unregister the menu entries.  Since this is
+a very common thing for packages to do, why should each maintainer rewrite all
+this on their own, sometimes with bugs?  Also, supposing the menu directory
+changed, every package would have to be changed.
+</para>
+<para>
+Helper scripts take care of these issues.  Assuming you comply with the
+conventions expected by the helper script, the helper takes care of all the
+details.  Changes in policy can be made in the helper script; then packages
+just need to be rebuilt with the new version of the helper and no other
+changes.
+</para>
+<para>
+<xref linkend="tools"/> contains a couple of different helpers.  The most
+common and best (in our opinion) helper system is <systemitem
+role="package">debhelper</systemitem>.  Previous helper systems, such as
+<systemitem role="package">debmake</systemitem>, were monolithic: you couldn't
+pick and choose which part of the helper you found useful, but had to use the
+helper to do everything.  <systemitem role="package">debhelper</systemitem>,
+however, is a number of separate little <command>dh_*</command> programs.  For
+instance, <command>dh_installman</command> installs and compresses man pages,
+<command>dh_installmenu</command> installs menu files, and so on.  Thus, it
+offers enough flexibility to be able to use the little helper scripts, where
+useful, in conjunction with hand-crafted commands in
+<filename>debian/rules</filename>.
+</para>
+<para>
+You can get started with <systemitem role="package">debhelper</systemitem> by
+reading <citerefentry> <refentrytitle>debhelper</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that come
+with the package.  <command>dh_make</command>, from the <systemitem
+role="package">dh-make</systemitem> package (see <xref linkend="dh-make"/> ),
+can be used to convert a vanilla source package to a <systemitem
+role="package">debhelper</systemitem>ized package.  This shortcut, though,
+should not convince you that you do not need to bother understanding the
+individual <command>dh_*</command> helpers.  If you are going to use a helper,
+you do need to take the time to learn to use that helper, to learn its
+expectations and behavior.
+</para>
+<para>
+Some people feel that vanilla <filename>debian/rules</filename> files are
+better, since you don't have to learn the intricacies of any helper system.
+This decision is completely up to you.  Use what works for you.  Many examples
+of vanilla <filename>debian/rules</filename> files are available at <ulink
+url="http://arch.debian.org/arch/private/srivasta/"></ulink>.
+</para>
+</section>
+
+<section id="multiple-patches">
+<title>Separating your patches into multiple files</title>
+<para>
+Big, complex packages may have many bugs that you need to deal with.  If you
+correct a number of bugs directly in the source, and you're not careful, it can
+get hard to differentiate the various patches that you applied.  It can get
+quite messy when you have to update the package to a new upstream version which
+integrates some of the fixes (but not all).  You can't take the total set of
+diffs (e.g., from <filename>.diff.gz</filename>) and work out which patch sets
+to back out as a unit as bugs are fixed upstream.
+</para>
+<para>
+Unfortunately, the packaging system as such currently doesn't provide for
+separating the patches into several files.  Nevertheless, there are ways to
+separate patches: the patch files are shipped within the Debian patch file
+(<filename>.diff.gz</filename>), usually within the
+<filename>debian/</filename> directory.  The only difference is that they
+aren't applied immediately by dpkg-source, but by the <literal>build</literal>
+rule of <filename>debian/rules</filename>.  Conversely, they are reverted in
+the <literal>clean</literal> rule.
+</para>
+<para>
+<command>dbs</command> is one of the more popular approaches to this.  It does
+all of the above, and provides a facility for creating new and updating old
+patches.  See the package <systemitem role="package">dbs</systemitem> for more
+information and <systemitem role="package">hello-dbs</systemitem> for an
+example.
+</para>
+<para>
+<command>dpatch</command> also provides these facilities, but it's intended to
+be even easier to use.  See the package <systemitem
+role="package">dpatch</systemitem> for documentation and examples (in
+<filename>/usr/share/doc/dpatch</filename>).
+</para>
+</section>
+
+<section id="multiple-binary">
+<title>Multiple binary packages</title>
+<para>
+A single source package will often build several binary packages, either to
+provide several flavors of the same software (e.g., the <systemitem
+role="package">vim</systemitem> source package) or to make several small
+packages instead of a big one (e.g., so the user can install only the subset
+needed, and thus save some disk space).
+</para>
+<para>
+The second case can be easily managed in <filename>debian/rules</filename>.
+You just need to move the appropriate files from the build directory into the
+package's temporary trees.  You can do this using <command>install</command> or
+<command>dh_install</command> from <systemitem
+role="package">debhelper</systemitem>.  Be sure to check the different
+permutations of the various packages, ensuring that you have the inter-package
+dependencies set right in <filename>debian/control</filename>.
+</para>
+<para>
+The first case is a bit more difficult since it involves multiple recompiles of
+the same software but with different configuration options.  The <systemitem
+role="package">vim</systemitem> source package is an example of how to manage
+this using an hand-crafted <filename>debian/rules</filename> file.
+</para>
+</section>
+
+</section>
+
+<section id="bpp-debian-control">
+<title>Best practices for <filename>debian/control</filename></title>
+<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
+on package descriptions</ulink>.
+</para>
+<para>
+The description of the package, as defined by the corresponding field in the
+<filename>control</filename> file, contains both the package synopsis and the
+long description for the package.  <xref linkend="bpp-desc-basics"/> describes
+common guidelines for both parts of the package description.  Following that,
+<xref linkend="bpp-pkg-synopsis"/> provides guidelines specific to the
+synopsis, and <xref linkend="bpp-pkg-desc"/> contains guidelines specific to
+the description.
+</para>
+<section id="bpp-desc-basics">
+<title>General guidelines for package descriptions</title>
+<para>
+The package description should be written for the average likely user, the
+average person who will use and benefit from the package.  For instance,
+development packages are for developers, and can be technical in their
+language.  More general-purpose applications, such as editors, should be
+written for a less technical user.
+</para>
+<para>
+Our review of package descriptions lead us to conclude that most package
+descriptions are technical, that is, are not written to make sense for
+non-technical users.  Unless your package really is only for technical users,
+this is a problem.
+</para>
+<para>
+How do you write for non-technical users?  Avoid jargon.  Avoid referring to
+other applications or frameworks that the user might not be familiar with —
+GNOME or KDE is fine, since users are probably familiar with these terms, but
+GTK+ is probably not.  Try not to assume any knowledge at all.  If you must use
+technical terms, introduce them.
+</para>
+<para>
+Be objective.  Package descriptions are not the place for advocating your
+package, no matter how much you love it.  Remember that the reader may not care
+about the same things you care about.
+</para>
+<para>
+References to the names of any other software packages, protocol names,
+standards, or specifications should use their canonical forms, if one exists.
+For example, use X Window System, X11, or X; not X Windows, X-Windows, or X
+Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  Use PostScript, not
+Postscript or postscript.
+</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
+feedback.
+</para>
+</section>
+
+<section id="bpp-pkg-synopsis">
+<title>The package synopsis, or short description</title>
+<para>
+The synopsis line (the short description) should be concise.  It must not
+repeat the package's name (this is policy).
+</para>
+<para>
+It's a good idea to think of the synopsis as an appositive clause, not a full
+sentence.  An appositive clause is defined in WordNet as a grammatical relation
+between a word and a noun phrase that follows, e.g., Rudolph the red-nosed
+reindeer.  The appositive clause here is red-nosed reindeer.  Since the
+synopsis is a clause, rather than a full sentence, we recommend that it neither
+start with a capital nor end with a full stop (period).  It should also not
+begin with an article, either definite (the) or indefinite (a or an).
+</para>
+<para>
+It might help to imagine that the synopsis is combined with the package name in
+the following way:
+</para>
+<screen>
+<replaceable>package-name</replaceable> is a <replaceable>synopsis</replaceable>.
+</screen>
+<para>
+Alternatively, it might make sense to think of it as
+</para>
+<screen>
+<replaceable>package-name</replaceable> is <replaceable>synopsis</replaceable>.
+</screen>
+<para>
+or, if the package name itself is a plural (such as developers-tools)
+</para>
+<screen>
+<replaceable>package-name</replaceable> are <replaceable>synopsis</replaceable>.
+</screen>
+<para>
+This way of forming a sentence from the package name and synopsis should be
+considered as a heuristic and not a strict rule.  There are some cases where it
+doesn't make sense to try to form a sentence.
+</para>
+</section>
+
+<section id="bpp-pkg-desc">
+<title>The long description</title>
+<para>
+The long description is the primary information available to the user about a
+package before they install it.  It should provide all the information needed
+to let the user decide whether to install the package.  Assume that the user
+has already read the package synopsis.
+</para>
+<para>
+The long description should consist of full and complete sentences.
+</para>
+<para>
+The first paragraph of the long description should answer the following
+questions: what does the package do?  what task does it help the user
+accomplish?  It is important to describe this in a non-technical way, unless of
+course the audience for the package is necessarily technical.
+</para>
+<para>
+The following paragraphs should answer the following questions: Why do I as a
+user need this package?  What other features does the package have?  What
+outstanding features and deficiencies are there compared to other packages
+(e.g., if you need X, use Y instead)?  Is this package related to other
+packages in some way that is not handled by the package manager (e.g., this is
+the client for the foo server)?
+</para>
+<para>
+Be careful to avoid spelling and grammar mistakes.  Ensure that you spell-check
+it.  Both <command>ispell</command> and <command>aspell</command> have special
+modes for checking <filename>debian/control</filename> files:
+</para>
+<screen>
+ -d american -g debian/control
+</screen>
+<screen>
+ -d en -D -c debian/control
+</screen>
+<para>
+Users usually expect these questions to be answered in the package description:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+What does the package do?  If it is an add-on to another package, then the
+short description of the package we are an add-on to should be put in here.
+</para>
+</listitem>
+<listitem>
+<para>
+Why should I want this package?  This is related to the above, but not the same
+(this is a mail user agent; this is cool, fast, interfaces with PGP and LDAP
+and IMAP, has features X, Y, and Z).
+</para>
+</listitem>
+<listitem>
+<para>
+If this package should not be installed directly, but is pulled in by another
+package, this should be mentioned.
+</para>
+</listitem>
+<listitem>
+<para>
+If the package is experimental, or there are other reasons it should not be
+used, if there are other packages that should be used instead, it should be
+here as well.
+</para>
+</listitem>
+<listitem>
+<para>
+How is this package different from the competition?  Is it a better
+implementation?  more features?  different features?  Why should I choose this
+package.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="bpp-upstream-info">
+<title>Upstream home page</title>
+<para>
+We recommend that you add the URL for the package's home page to the package
+description in <filename>debian/control</filename>.  This information should be
+added at the end of description, using the following format:
+</para>
+<screen>
+ .
+  Homepage: http://some-project.some-place.org/
+</screen>
+<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>.
+</para>
+<para>
+If there is no home page for the software, this should naturally be left out.
+</para>
+<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
+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.
+</para>
+</section>
+
+<section id="bpp-vcs">
+<title>Version Control System location</title>
+<para>
+There are additional fields for the location of the Version Control System in
+<filename>debian/control</filename>.
+</para>
+<section id="s6.2.5.1">
+<title>XS-Vcs-Browser</title>
+<para>
+Value of this field should be a <literal>http://</literal> URL pointing to a
+web-browsable copy of the Version Control System repository used to maintain
+the given package, if available.
+</para>
+<para>
+The information is meant to be useful for the final user, willing to browse the
+latest work done on the package (e.g.  when looking for the patch fixing a bug
+tagged as <literal>pending</literal> in the bug tracking system).
+</para>
+</section>
+
+<section id="s6.2.5.2">
+<title>XS-Vcs-*</title>
+<para>
+Value of this field should be a string identifying unequivocally the location
+of the Version Control System repository used to maintain the given package, if
+available.  <literal>*</literal> identify the Version Control System; currently
+the following systems are supported by the package tracking system:
+<literal>arch</literal>, <literal>bzr</literal> (Bazaar),
+<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>,
+<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone),
+<literal>svn</literal> (Subversion).  It is allowed to specify different VCS
+fields for the same package: they will all be shown in the PTS web interface.
+</para>
+<para>
+The information is meant to be useful for a user knowledgeable in the given
+Version Control System and willing to build the current version of a package
+from the VCS sources.  Other uses of this information might include automatic
+building of the latest VCS version of the given package.  To this end the
+location pointed to by the field should better be version agnostic and point to
+the main branch (for VCSs supporting such a concept).  Also, the location
+pointed to should be accessible to the final user; fulfilling this requirement
+might imply pointing to an anonymous access of the repository instead of
+pointing to an SSH-accessible version of the same.
+</para>
+<para>
+In the following example, an instance of the field for a Subversion repository
+of the <systemitem role="package">vim</systemitem> package is shown.  Note how
+the URL is in the <literal>svn://</literal> scheme (instead of
+<literal>svn+ssh://</literal>) and how it points to the
+<filename>trunk/</filename> branch.  The use of the
+<literal>XS-Vcs-Browser</literal> field described above is also shown.
+</para>
+<screen>
+  Source: vim
+  Section: editors
+  Priority: optional
+  &lt;snip&gt;
+  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
+  XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
+</screen>
+</section>
+
+</section>
+
+</section>
+
+<section id="bpp-debian-changelog">
+<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
+on changelog files</ulink>.
+</para>
+<section id="bpp-changelog-do">
+<title>Writing useful changelog entries</title>
+<para>
+The changelog entry for a package revision documents changes in that revision,
+and only them.  Concentrate on describing significant and user-visible changes
+that were made since the last version.
+</para>
+<para>
+Focus on <emphasis>what</emphasis> was changed — who, how and when are
+usually less important.  Having said that, remember to politely attribute
+people who have provided notable help in making the package (e.g., those who
+have sent in patches).
+</para>
+<para>
+There's no need to elaborate the trivial and obvious changes.  You can also
+aggregate several changes in one entry.  On the other hand, don't be overly
+terse if you have undertaken a major change.  Be especially clear if there are
+changes that affect the behaviour of the program.  For further explanations,
+use the <filename>README.Debian</filename> file.
+</para>
+<para>
+Use common English so that the majority of readers can comprehend it.  Avoid
+abbreviations, tech-speak and jargon when explaining changes that close bugs,
+especially for bugs filed by users that did not strike you as particularly
+technically savvy.  Be polite, don't swear.
+</para>
+<para>
+It is sometimes desirable to prefix changelog entries with the names of the
+files that were changed.  However, there's no need to explicitly list each and
+every last one of the changed files, especially if the change was small or
+repetitive.  You may use wildcards.
+</para>
+<para>
+When referring to bugs, don't assume anything.  Say what the problem was, how
+it was fixed, and append the closes: #nnnnn string.  See <xref
+linkend="upload-bugfix"/> for more information.
+</para>
+</section>
+
+<section id="bpp-changelog-misconceptions">
+<title>Common misconceptions about changelog entries</title>
+<para>
+The changelog entries should <emphasis role="strong">not</emphasis> document
+generic packaging issues (Hey, if you're looking for foo.conf, it's in
+/etc/blah/.), since administrators and users are supposed to be at least
+remotely acquainted with how such things are generally arranged on Debian
+systems.  Do, however, mention if you change the location of a configuration
+file.
+</para>
+<para>
+The only bugs closed with a changelog entry should be those that are actually
+fixed in the same package revision.  Closing unrelated bugs in the changelog is
+bad practice.  See <xref linkend="upload-bugfix"/> .
+</para>
+<para>
+The changelog entries should <emphasis role="strong">not</emphasis> be used for
+random discussion with bug reporters (I don't see segfaults when starting foo
+with option bar; send in more info), general statements on life, the universe
+and everything (sorry this upload took me so long, but I caught the flu), or
+pleas for help (the bug list on this package is huge, please lend me a hand).
+Such things usually won't be noticed by their target audience, but may annoy
+people who wish to read information about actual changes in the package.  See
+<xref linkend="bug-answering"/> for more information on how to use the bug
+tracking system.
+</para>
+<para>
+It is an old tradition to acknowledge bugs fixed in non-maintainer uploads in
+the first changelog entry of the proper maintainer upload.  As we have version
+tracking now, it is enough to keep the NMUed changelog entries and just mention
+this fact in your own changelog entry.
+</para>
+</section>
+
+<section id="bpp-changelog-errors">
+<title>Common errors in changelog entries</title>
+<para>
+The following examples demonstrate some common errors or examples of bad style
+in changelog entries.
+</para>
+<screen>
+  * Fixed all outstanding bugs.
+</screen>
+<para>
+This doesn't tell readers anything too useful, obviously.
+</para>
+<screen>
+  * Applied patch from Jane Random.
+</screen>
+<para>
+What was the patch about?
+</para>
+<screen>
+  * Late night install target overhaul.
+</screen>
+<para>
+Overhaul which accomplished what?  Is the mention of late night supposed to
+remind us that we shouldn't trust that code?
+</para>
+<screen>
+  * Fix vsync FU w/ ancient CRTs.
+</screen>
+<para>
+Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a
+curse word!) was actually about, or how it was fixed.
+</para>
+<screen>
+  * This is not a bug, closes: #nnnnnn.
+</screen>
+<para>
+First of all, there's absolutely no need to upload the package to convey this
+information; instead, use the bug tracking system.  Secondly, there's no
+explanation as to why the report is not a bug.
+</para>
+<screen>
+  * Has been fixed for ages, but I forgot to close; closes: #54321.
+</screen>
+<para>
+If for some reason you didn't mention the bug number in a previous changelog
+entry, there's no problem, just close the bug normally in the BTS.  There's no
+need to touch the changelog file, presuming the description of the fix is
+already in (this applies to the fixes by the upstream authors/maintainers as
+well, you don't have to track bugs that they fixed ages ago in your changelog).
+</para>
+<screen>
+  * Closes: #12345, #12346, #15432
+</screen>
+<para>
+Where's the description?  If you can't think of a descriptive message, start by
+inserting the title of each different bug.
+</para>
+</section>
+
+<section id="bpp-news-debian">
+<title>Supplementing changelogs with NEWS.Debian files</title>
+<para>
+Important news about changes in a package can also be put in NEWS.Debian files.
+The news will be displayed by tools like apt-listchanges, before all the rest
+of the changelogs.  This is the preferred means to let the user know about
+significant changes in a package.  It is better than using debconf notes since
+it is less annoying and the user can go back and refer to the NEWS.Debian file
+after the install.  And it's better than listing major changes in
+README.Debian, since the user can easily miss such notes.
+</para>
+<para>
+The file format is the same as a debian changelog file, but leave off the
+asterisks and describe each news item with a full paragraph when necessary
+rather than the more concise summaries that would go in a changelog.  It's a
+good idea to run your file through dpkg-parsechangelog to check its formatting
+as it will not be automatically checked during build as the changelog is.  Here
+is an example of a real NEWS.Debian file:
+</para>
+<screen>
+ (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
+    functionality provided with that script, please install the new
+    package.
+
+ -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 -0500
+</screen>
+<para>
+The NEWS.Debian file is installed as
+/usr/share/doc/&lt;package&gt;/NEWS.Debian.gz.  It is compressed, and always
+has that name even in Debian native packages.  If you use debhelper,
+dh_installchangelogs will install debian/NEWS files for you.
+</para>
+<para>
+Unlike changelog files, you need not update NEWS.Debian files with every
+release.  Only update them if you have something particularly newsworthy that
+user should know about.  If you have no news at all, there's no need to ship a
+NEWS.Debian file in your package.  No news is good news!
+</para>
+</section>
+
+</section>
+
+<section id="bpp-debian-maint-scripts">
+<title>Best practices for maintainer scripts</title>
+<para>
+Maintainer scripts include the files <filename>debian/postinst</filename>,
+<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and
+<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>.
+</para>
+<para>
+Maintainer scripts must be idempotent.  That means that you need to make sure
+nothing bad will happen if the script is called twice where it would usually be
+called once.
+</para>
+<para>
+Standard input and output may be redirected (e.g.  into pipes) for logging
+purposes, so don't rely on them being a tty.
+</para>
+<para>
+All prompting or interactive configuration should be kept to a minimum.  When
+it is necessary, you should use the <systemitem
+role="package">debconf</systemitem> package for the interface.  Remember that
+prompting in any case can only be in the <literal>configure</literal> stage of
+the <filename>postinst</filename> script.
+</para>
+<para>
+Keep the maintainer scripts as simple as possible.  We suggest you use pure
+POSIX shell scripts.  Remember, if you do need any bash features, the
+maintainer script must have a bash shebang line.  POSIX shell or Bash are
+preferred to Perl, since they enable <systemitem
+role="package">debhelper</systemitem> to easily add bits to the scripts.
+</para>
+<para>
+If you change your maintainer scripts, be sure to test package removal, double
+installation, and purging.  Be sure that a purged package is completely gone,
+that is, it must remove any files created, directly or indirectly, in any
+maintainer script.
+</para>
+<para>
+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>
+<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>
+<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,
+and false if not.  This is really the most portable way, since <literal>command
+-v</literal>, <command>type</command>, and <command>which</command> are not
+POSIX.
+</para>
+<para>
+While <command>which</command> is an acceptable alternative, since it is from
+the required <systemitem role="package">debianutils</systemitem> package, it's
+not on the root partition.  That is, it's in <filename>/usr/bin</filename>
+rather than <filename>/bin</filename>, so one can't use it in scripts which are
+run before the <filename>/usr</filename> partition is mounted.  Most scripts
+won't have this problem, though.
+</para>
+</section>
+
+<section id="bpp-config-mgmt">
+<title>Configuration management with <systemitem role="package">debconf</systemitem></title>
+<para>
+<systemitem role="package">Debconf</systemitem> is a configuration management
+system which can be used by all the various packaging scripts
+(<filename>postinst</filename> mainly) to request feedback from the user
+concerning how to configure the package.  Direct user interactions must now be
+avoided in favor of <systemitem role="package">debconf</systemitem>
+interaction.  This will enable non-interactive installations in the future.
+</para>
+<para>
+Debconf is a great tool but it is often poorly used.  Many common mistakes are
+listed in the <citerefentry> <refentrytitle>debconf-devel</refentrytitle>
+<manvolnum>7</manvolnum> </citerefentry> man page.  It is something that you
+must read if you decide to use debconf.  Also, we document some best practices
+here.
+</para>
+<para>
+These guidelines include some writing style and typography recommendations,
+general considerations about debconf usage as well as more specific
+recommendations for some parts of the distribution (the installation system for
+instance).
+</para>
+<section id="s6.5.1">
+<title>Do not abuse debconf</title>
+<para>
+Since debconf appeared in Debian, it has been widely abused and several
+criticisms received by the Debian distribution come from debconf abuse with the
+need of answering a wide bunch of questions before getting any little thing
+installed.
+</para>
+<para>
+Keep usage notes to what they belong: the NEWS.Debian, or README.Debian file.
+Only use notes for important notes which may directly affect the package
+usability.  Remember that notes will always block the install until confirmed
+or bother the user by email.
+</para>
+<para>
+Carefully choose the questions priorities in maintainer scripts.  See
+<citerefentry> <refentrytitle>debconf-devel</refentrytitle>
+<manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most
+questions should use medium and low priorities.
+</para>
+</section>
+
+<section id="s6.5.2">
+<title>General recommendations for authors and translators</title>
+<section id="s6.5.2.1">
+<title>Write correct English</title>
+<para>
+Most Debian package maintainers are not native English speakers.  So, writing
+properly phrased templates may not be easy for them.
+</para>
+<para>
+Please use (and abuse) <email>debian-l10n-english@lists.debian.org</email>
+mailing list.  Have your templates proofread.
+</para>
+<para>
+Badly written templates give a poor image of your package, of your work...or
+even of Debian itself.
+</para>
+<para>
+Avoid technical jargon as much as possible.  If some terms sound common to you,
+they may be impossible to understand for others.  If you cannot avoid them, try
+to explain them (use the extended description).  When doing so, try to balance
+between verbosity and simplicity.
+</para>
+</section>
+
+<section id="s6.5.2.2">
+<title>Be kind to translators</title>
+<para>
+Debconf templates may be translated.  Debconf, along with its sister package
+<command>po-debconf</command> offers a simple framework for getting templates
+translated by translation teams or even individuals.
+</para>
+<para>
+Please use gettext-based templates.  Install <systemitem
+role="package">po-debconf</systemitem> on your development system and read its
+documentation (man po-debconf is a good start).
+</para>
+<para>
+Avoid changing templates too often.  Changing templates text induces more work
+to translators which will get their translation fuzzied.  If you plan changes
+to your original templates, please contact translators.  Most active
+translators are very responsive and getting their work included along with your
+modified templates will save you additional uploads.  If you use gettext-based
+templates, the translator's name and e-mail addresses are mentioned in the po
+files headers.
+</para>
+<para>
+The use of the <command>podebconf-report-po</command> from the po-debconf
+package is highly recommended to warn translators which have incomplete
+translations and request them for updates.
+</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.
+</para>
+<para>
+Calls for translations posted to <email>debian-i18n@lists.debian.org</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
+avoid duplicate work.
+</para>
+</section>
+
+<section id="s6.5.2.3">
+<title>Unfuzzy complete translations when correcting typos and spelling</title>
+<para>
+When the text of a debconf template is corrected and you are <emphasis
+role="strong">sure</emphasis> that the change does <emphasis
+role="strong">not</emphasis> affect translations, please be kind to translators
+and unfuzzy their translations.
+</para>
+<para>
+If you don't do so, the whole template will not be translated as long as a
+translator will send you an update.
+</para>
+<para>
+To <emphasis role="strong">unfuzzy</emphasis> translations, you can proceed the
+following way:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Put all incomplete PO files out of the way.  You can check the completeness by
+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>
+</listitem>
+<listitem>
+<para>
+move all files which report either fuzzy strings to a temporary place.  Files
+which report no fuzzy strings (only translated and untranslated) will be kept
+in place.
+</para>
+</listitem>
+<listitem>
+<para>
+now <emphasis role="strong">and now only</emphasis>, modify the template for
+the typos and check again that translation are not impacted (typos, spelling
+errors, sometimes typographical corrections are usually OK)
+</para>
+</listitem>
+<listitem>
+<para>
+run <command>debconf-updatepo</command>.  This will fuzzy all strings you
+modified in translations.  You can see this by running the above again
+</para>
+</listitem>
+<listitem>
+<para>
+use the following command:
+</para>
+<screen>
+ i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done
+</screen>
+</listitem>
+<listitem>
+<para>
+move back to debian/po the files which showed fuzzy strings in the first step
+</para>
+</listitem>
+<listitem>
+<para>
+run <command>debconf-updatepo</command> again
+</para>
+</listitem>
+</orderedlist>
+</section>
+
+<section id="s6.5.2.4">
+<title>Do not make assumptions about interfaces</title>
+<para>
+Templates text should not make reference to widgets belonging to some debconf
+interfaces.  Sentences like If you answer Yes...  have no meaning for users of
+graphical interfaces which use checkboxes for boolean questions.
+</para>
+<para>
+String templates should also avoid mentioning the default values in their
+description.  First, because this is redundant with the values seen by the
+users.  Also, because these default values may be different from the maintainer
+choices (for instance, when the debconf database was preseeded).
+</para>
+<para>
+More generally speaking, try to avoid referring to user actions.  Just give
+facts.
+</para>
+</section>
+
+<section id="s6.5.2.5">
+<title>Do not use first person</title>
+<para>
+You should avoid the use of first person (I will do this...  or We
+recommend...).  The computer is not a person and the Debconf templates do not
+speak for the Debian developers.  You should use neutral construction.  Those
+of you who already wrote scientific publications, just write your templates
+like you would write a scientific paper.  However, try using action voice if
+still possible, like Enable this if ...  instead of This can be enabled if ....
+</para>
+</section>
+
+<section id="s6.5.2.6">
+<title>Be gender neutral</title>
+<para>
+The world is made of men and women.  Please use gender-neutral constructions in
+your writing.
+</para>
+</section>
+
+</section>
+
+<section id="s6.5.3">
+<title>Templates fields definition</title>
+<para>
+This part gives some information which is mostly taken from the <citerefentry>
+<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum>
+</citerefentry> manual page.
+</para>
+<section id="s6.5.3.1">
+<title>Type</title>
+<section id="s6.5.3.1.1">
+<title>string:</title>
+<para>
+Results in a free-form input field that the user can type any string into.
+</para>
+</section>
+
+<section id="s6.5.3.1.2">
+<title>password:</title>
+<para>
+Prompts the user for a password.  Use this with caution; be aware that the
+password the user enters will be written to debconf's database.  You should
+probably clean that value out of the database as soon as is possible.
+</para>
+</section>
+
+<section id="s6.5.3.1.3">
+<title>boolean:</title>
+<para>
+A true/false choice.  Remember: true/false, <emphasis role="strong">not
+yes/no</emphasis>...
+</para>
+</section>
+
+<section id="s6.5.3.1.4">
+<title>select:</title>
+<para>
+A choice between one of a number of values.  The choices must be specified in a
+field named 'Choices'.  Separate the possible values with commas and spaces,
+like this: Choices: yes, no, maybe
+</para>
+</section>
+
+<section id="s6.5.3.1.5">
+<title>multiselect:</title>
+<para>
+Like the select data type, except the user can choose any number of items from
+the choices list (or chose none of them).
+</para>
+</section>
+
+<section id="s6.5.3.1.6">
+<title>note:</title>
+<para>
+Rather than being a question per se, this datatype indicates a note that can be
+displayed to the user.  It should be used only for important notes that the
+user really should see, since debconf will go to great pains to make sure the
+user sees it; halting the install for them to press a key, and even mailing the
+note to them in some cases.
+</para>
+</section>
+
+<section id="s6.5.3.1.7">
+<title>text:</title>
+<para>
+This type is now considered obsolete: don't use it.
+</para>
+</section>
+
+<section id="s6.5.3.1.8">
+<title>error:</title>
+<para>
+This type is designed to handle error messages.  It is mostly similar to the
+note type.  Frontends may present it differently (for instance, the dialog
+frontend of cdebconf draws a red screen instead of the usual blue one).
+</para>
+<para>
+It is recommended to use this type for any message that needs user attention
+for a correction of any kind.
+</para>
+</section>
+
+</section>
+
+<section id="s6.5.3.2">
+<title>Description: short and extended description</title>
+<para>
+Template descriptions have two parts: short and extended.  The short
+description is in the Description: line of the template.
+</para>
+<para>
+The short description should be kept short (50 characters or so) so that it may
+be accomodated by most debconf interfaces.  Keeping it short also helps
+translators, as usually translations tend to end up being longer than the
+original.
+</para>
+<para>
+The short description should be able to stand on its own.  Some interfaces do
+not show the long description by default, or only if the user explicitely asks
+for it or even do not show it at all.  Avoid things like What do you want to
+do?
+</para>
+<para>
+The short description does not necessarily have to be a full sentence.  This is
+part of the keep it short and efficient recommendation.
+</para>
+<para>
+The extended description should not repeat the short description word for word.
+If you can't think up a long description, then first, think some more.  Post to
+debian-devel.  Ask for help.  Take a writing class!  That extended description
+is important.  If after all that you still can't come up with anything, leave
+it blank.
+</para>
+<para>
+The extended description should use complete sentences.  Paragraphs should be
+kept short for improved readability.  Do not mix two ideas in the same
+paragraph but rather use another paragraph.
+</para>
+<para>
+Don't be too verbose.  User tend to ignore too long screens.  20 lines are by
+experience a border you shouldn't cross, because that means that in the
+classical dialog interface, people will need to scroll, and lot of people just
+don't do that.
+</para>
+<para>
+The extended description should <emphasis role="strong">never</emphasis>
+include a question.
+</para>
+<para>
+For specific rules depending on templates type (string, boolean, etc.), please
+read below.
+</para>
+</section>
+
+<section id="s6.5.3.3">
+<title>Choices</title>
+<para>
+This field should be used for Select and Multiselect types.  It contains the
+possible choices which will be presented to users.  These choices should be
+separated by commas.
+</para>
+</section>
+
+<section id="s6.5.3.4">
+<title>Default</title>
+<para>
+This field is optional.  It contains the default answer for string, select and
+multiselect templates.  For multiselect templates, it may contain a
+comma-separated list of choices.
+</para>
+</section>
+
+</section>
+
+<section id="s6.5.4">
+<title>Templates fields specific style guide</title>
+<section id="s6.5.4.1">
+<title>Type field</title>
+<para>
+No specific indication except: use the appropriate type by referring to the
+previous section.
+</para>
+</section>
+
+<section id="s6.5.4.2">
+<title>Description field</title>
+<para>
+Below are specific instructions for properly writing the Description (short and
+extended) depending on the template type.
+</para>
+<section id="s6.5.4.2.1">
+<title>String/password templates</title>
+<itemizedlist>
+<listitem>
+<para>
+The short description is a prompt and <emphasis role="strong">not</emphasis> a
+title.  Avoid question style prompts (IP Address?) in favour of opened prompts
+(IP address:).  The use of colons is recommended.
+</para>
+</listitem>
+<listitem>
+<para>
+The extended description is a complement to the short description.  In the
+extended part, explain what is being asked, rather than ask the same question
+again using longer words.  Use complete sentences.  Terse writing style is
+strongly discouraged.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s6.5.4.2.2">
+<title>Boolean templates</title>
+<itemizedlist>
+<listitem>
+<para>
+The short description should be phrased in the form of a question which should
+be kept short and should generally end with a question mark.  Terse writing
+style is permitted and even encouraged if the question is rather long (remember
+that translations are often longer than original versions)
+</para>
+</listitem>
+<listitem>
+<para>
+Again, please avoid referring to specific interface widgets.  A common mistake
+for such templates is if you answer Yes-type constructions.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s6.5.4.2.3">
+<title>Select/Multiselect</title>
+<itemizedlist>
+<listitem>
+<para>
+The short description is a prompt and <emphasis role="strong">not</emphasis> a
+title.  Do <emphasis role="strong">not</emphasis> use useless Please choose...
+constructions.  Users are clever enough to figure out they have to choose
+something...:)
+</para>
+</listitem>
+<listitem>
+<para>
+The extended description will complete the short description.  It may refer to
+the available choices.  It may also mention that the user may choose more than
+one of the available choices, if the template is a multiselect one (although
+the interface often makes this clear).
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s6.5.4.2.4">
+<title>Notes</title>
+<itemizedlist>
+<listitem>
+<para>
+The short description should be considered to be a *title*.
+</para>
+</listitem>
+<listitem>
+<para>
+The extended description is what will be displayed as a more detailed
+explanation of the note.  Phrases, no terse writing style.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="strong">Do not abuse debconf.</emphasis> Notes are the most
+common way to abuse debconf.  As written in debconf-devel manual page: it's
+best to use them only for warning about very serious problems.  The NEWS.Debian
+or README.Debian files are the appropriate location for a lot of notes.  If, by
+reading this, you consider converting your Note type templates to entries in
+NEWS/Debian or README.Debian, plus consider keeping existing translations for
+the future.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+</section>
+
+<section id="s6.5.4.3">
+<title>Choices field</title>
+<para>
+If the Choices are likely to change often, please consider using the __Choices
+trick.  This will split each individual choice into a single string, which will
+considerably help translators for doing their work.
+</para>
+</section>
+
+<section id="s6.5.4.4">
+<title>Default field</title>
+<para>
+If the default value, for a select template, is likely to vary depending on the
+user language (for instance, if the choice is a language choice), please use
+the _DefaultChoice trick.
+</para>
+<para>
+This special field allow translators to put the most appropriate choice
+according to their own language.  It will become the default choice when their
+language is used while your own mentioned Default Choice will be used chan
+using English.
+</para>
+<para>
+Example, taken from the geneweb package templates:
+</para>
+<screen>
+: 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
+# instead of the default.
+# WARNING : you MUST use the ENGLISH FORM of your language
+# For instance, the french translator will need to put French (fr) here.
+_DefaultChoice: English (en)[ translators, please see comment in PO files]
+_Description: Geneweb default language:
+</screen>
+<para>
+Note the use of brackets which allow internal comments in debconf fields.  Also
+note the use of comments which will show up in files the translators will work
+with.
+</para>
+<para>
+The comments are needed as the DefaultChoice trick is a bit confusing: the
+translators may put their own choice
+</para>
+</section>
+
+<section id="s6.5.4.5">
+<title>Default field</title>
+<para>
+Do NOT use empty default field.  If you don't want to use default values, do
+not use Default at all.
+</para>
+<para>
+If you use po-debconf (and you <emphasis role="strong">should</emphasis>, see
+2.2), consider making this field translatable, if you think it may be
+translated.
+</para>
+<para>
+If the default value may vary depending on language/country (for instance the
+default value for a language choice), consider using the special _DefaultChoice
+type documented in <citerefentry> <refentrytitle>po-debconf</refentrytitle>
+<manvolnum>7</manvolnum> </citerefentry>).
+</para>
+</section>
+
+</section>
+
+</section>
+
+<section id="bpp-i18n">
+<title>Internationalization</title>
+<section id="bpp-i18n-debconf">
+<title>Handling debconf translations</title>
+<para>
+Like porters, translators have a difficult task.  They work on many packages
+and must collaborate with many different maintainers.  Moreover, most of the
+time, they are not native English speakers, so you may need to be particularly
+patient with them.
+</para>
+<para>
+The goal of <systemitem role="package">debconf</systemitem> was to make
+packages configuration easier for maintainers and for users.  Originally,
+translation of debconf templates was handled with
+<command>debconf-mergetemplate</command>.  However, that technique is now
+deprecated; the best way to accomplish <systemitem
+role="package">debconf</systemitem> internationalization is by using the
+<systemitem role="package">po-debconf</systemitem> package.  This method is
+easier both for maintainer and translators; transition scripts are provided.
+</para>
+<para>
+Using <systemitem role="package">po-debconf</systemitem>, the translation is
+stored in <filename>po</filename> files (drawing from
+<command>gettext</command> translation techniques).  Special template files
+contain the original messages and mark which fields are translatable.  When you
+change the value of a translatable field, by calling
+<command>debconf-updatepo</command>, the translation is marked as needing
+attention from the translators.  Then, at build time, the
+<command>dh_installdebconf</command> program takes care of all the needed magic
+to add the template along with the up-to-date translations into the binary
+packages.  Refer to the <citerefentry>
+<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum>
+</citerefentry> manual page for details.
+</para>
+</section>
+
+<section id="bpp-i18n-docs">
+<title>Internationalized documentation</title>
+<para>
+Internationalizing documentation is crucial for users, but a lot of labor.
+There's no way to eliminate all that work, but you can make things easier for
+translators.
+</para>
+<para>
+If you maintain documentation of any size, its easier for translators if they
+have access to a source control system.  That lets translators see the
+differences between two versions of the documentation, so, for instance, they
+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
+]\|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
+the current revision of the file to be translated and, for a translated file,
+the revision of the original file the translation is based on.  You might wish
+to adapt and provide that in your CVS area.
+</para>
+<para>
+If you maintain XML or SGML documentation, we suggest that you isolate any
+language-independent information and define those as entities in a separate
+file which is included by all the different translations.  This makes it much
+easier, for instance, to keep URLs up to date across multiple files.
+</para>
+</section>
+
+</section>
+
+<section id="bpp-common-situations">
+<title>Common packaging situations</title>
+<section id="bpp-autotools">
+<title>Packages using <command>autoconf</command>/<command>automake</command></title>
+<para>
+Keeping <command>autoconf</command>'s <filename>config.sub</filename> and
+<filename>config.guess</filename> files up to date is critical for porters,
+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
+<systemitem role="package">autotools-dev</systemitem> package.  You're strongly
+encouraged to read this file and to follow the given recommendations.
+</para>
+</section>
+
+<section id="bpp-libraries">
+<title>Libraries</title>
+<para>
+Libraries are always difficult to package for various reasons.  The policy
+imposes many constraints to ease their maintenance and to make sure upgrades
+are as simple as possible when a new upstream version comes out.  Breakage in a
+library can result in dozens of dependent packages breaking.
+</para>
+<para>
+Good practices for library packaging have been grouped in <ulink
+url="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/">the library
+packaging guide</ulink>.
+</para>
+</section>
+
+<section id="bpp-docs">
+<title>Documentation</title>
+<para>
+Be sure to follow the <ulink
+url="http://www.debian.org/doc/debian-policy/ch-docs.html">Policy on
+documentation</ulink>.
+</para>
+<para>
+If your package contains documentation built from XML or SGML, we recommend you
+not ship the XML or SGML source in the binary package(s).  If users want the
+source of the documentation, they should retrieve the source package.
+</para>
+<para>
+Policy specifies that documentation should be shipped in HTML format.  We also
+recommend shipping documentation in PDF and plain text format if convenient and
+if output of reasonable quality is possible.  However, it is generally not
+appropriate to ship plain text versions of documentation whose source format is
+HTML.
+</para>
+<para>
+Major shipped manuals should register themselves with <systemitem
+role="package">doc-base</systemitem> on installation.  See the <systemitem
+role="package">doc-base</systemitem> package documentation for more
+information.
+</para>
+</section>
+
+<section id="bpp-other">
+<title>Specific types of packages</title>
+<para>
+Several specific types of packages have special sub-policies and corresponding
+packaging rules and practices:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Perl related packages have a <ulink
+url="http://www.debian.org/doc/packaging-manuals/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).
+</para>
+</listitem>
+<listitem>
+<para>
+Python related packages have their python policy; see
+<filename>/usr/share/doc/python/python-policy.txt.gz</filename> in the
+<systemitem role="package">python</systemitem> package.
+</para>
+</listitem>
+<listitem>
+<para>
+Emacs related packages have the <ulink
+url="http://www.debian.org/doc/packaging-manuals/debian-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
+policy</ulink>.
+</para>
+</listitem>
+<listitem>
+<para>
+Ocaml related packages have their own policy, found in
+<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename> from the
+<systemitem role="package">ocaml</systemitem> package.  A good example is the
+<systemitem role="package">camlzip</systemitem> source package.
+</para>
+</listitem>
+<listitem>
+<para>
+Packages providing XML or SGML DTDs should conform to the recommendations found
+in the <systemitem role="package">sgml-base-doc</systemitem> package.
+</para>
+</listitem>
+<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>.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="bpp-archindepdata">
+<title>Architecture-independent data</title>
+<para>
+It is not uncommon to have a large amount of architecture-independent data
+packaged with a program.  For example, audio files, a collection of icons,
+wallpaper patterns, or other graphic files.  If the size of this data is
+negligible compared to the size of the rest of the package, it's probably best
+to keep it all in a single package.
+</para>
+<para>
+However, if the size of the data is considerable, consider splitting it out
+into a separate, architecture-independent package (_all.deb).  By doing this,
+you avoid needless duplication of the same data into eleven or more .debs, one
+per each architecture.  While this adds some extra overhead into the
+<filename>Packages</filename> files, it saves a lot of disk space on Debian
+mirrors.  Separating out architecture-independent data also reduces processing
+time of <command>lintian</command> or <command>linda</command> (see <xref
+linkend="tools-lint"/> ) when run over the entire Debian archive.
+</para>
+</section>
+
+<section id="bpp-locale">
+<title>Needing a certain locale during build</title>
+<para>
+If you need a certain locale during build, you can create a temporary file via
+this trick:
+</para>
+<para>
+If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL 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_NAME=en_IN
+LOCALE_CHARSET=UTF-8
+
+mkdir -p $LOCALE_PATH
+localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET
+
+# Using the locale
+LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date
+</screen>
+</section>
+
+<section id="bpp-transition">
+<title>Make transition packages deborphan compliant</title>
+<para>
+Deborphan is a program for helping users to detect which packages can safely be
+removed from the system, i.e.  the ones that have no packages depending on
+them.  The default operation is to search only within the libs and oldlibs
+sections, to hunt down unused libraries.  But when passed the right argument,
+it tries to catch other useless packages.
+</para>
+<para>
+For example, with --guess-dummy, deborphan tries to search all transitional
+packages which were needed for upgrade but which can now safely be removed.
+For that, it looks for the string dummy or transitional in their short
+description.
+</para>
+<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>
+.
+</para>
+</section>
+
+<section id="bpp-origtargz">
+<title>Best practices for <filename>orig.tar.gz</filename> files</title>
+<para>
+There are two kinds of original source tarballs: Pristine source and repackaged
+upstream source.
+</para>
+<section id="pristinesource">
+<title>Pristine source</title>
+<para>
+The defining characteristic of a pristine source tarball is that the
+.orig.tar.gz file is byte-for-byte identical to a tarball officially
+distributed by the upstream author.  <footnote><para> We cannot prevent
+upstream authors from changing the tarball they distribute without also
+incrementing the version number, so there can be no guarantee that a pristine
+tarball is identical to what upstream <emphasis>currently</emphasis>
+distributing at any point in time.  All that can be expected is that it is
+identical to something that upstream once <emphasis>did</emphasis> distribute.
+If a difference arises later (say, if upstream notices that he wasn't using
+maximal comression in his original distribution and then
+re-<literal>gzip</literal>s it), that's just too bad.  Since there is no good
+way to upload a new .orig.tar.gz for the same version, there is not even any
+point in treating this situation as a bug.  </para> </footnote> This makes it
+possible to use checksums to easily verify that all changes between Debian's
+version and upstream's are contained in the Debian diff.  Also, if the original
+source is huge, upstream authors and others who already have the upstream
+tarball can save download time if they want to inspect your packaging in
+detail.
+</para>
+<para>
+There is no universally accepted guidelines that upstream authors follow
+regarding to the directory structure inside their tarball, but
+<command>dpkg-source</command> is nevertheless able to deal with most upstream
+tarballs as pristine source.  Its strategy is equivalent to the following:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+It unpacks the tarball in an empty temporary directory by doing
+</para>
+<screen>
+ path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
+</screen>
+</listitem>
+<listitem>
+<para>
+If, after this, the temporary directory contains nothing but one directory and
+no other files, <command>dpkg-source</command> renames that directory to
+<literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.  The
+name of the top-level directory in the tarball does not matter, and is
+forgotten.
+</para>
+</listitem>
+<listitem>
+<para>
+Otherwise, the upstream tarball must have been packaged without a common
+top-level directory (shame on the upstream author!).  In this case,
+<command>dpkg-source</command> renames the temporary directory
+<emphasis>itself</emphasis> to
+<literal>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</literal>.
+</para>
+</listitem>
+</orderedlist>
+</section>
+
+<section id="repackagedorigtargz">
+<title>Repackaged upstream source</title>
+<para>
+You <emphasis role="strong">should</emphasis> upload packages with a pristine
+source tarball if possible, but there are various reasons why it might not be
+possible.  This is the case if upstream does not distribute the source as
+gzipped tar at all, or if upstream's tarball contains non-DFSG-free material
+that you must remove before uploading.
+</para>
+<para>
+In these cases the developer must construct a suitable .orig.tar.gz file
+himself.  We refer to such a tarball as a repackaged upstream source.  Note
+that a repackaged upstream source is different from a Debian-native package.  A
+repackaged source still comes with Debian-specific changes in a separate
+<literal>.diff.gz</literal> and still has a version number composed of
+<literal>&lt;upstream-version&gt;</literal> and
+<literal>&lt;debian-revision&gt;</literal>.
+</para>
+<para>
+There may be cases where it is desirable to repackage the source even though
+upstream distributes a <literal>.tar.gz</literal> that could in principle be
+used in its pristine form.  The most obvious is if
+<emphasis>significant</emphasis> space savings can be achieved by recompressing
+the tar archive or by removing genuinely useless cruft from the upstream
+archive.  Use your own discretion here, but be prepared to defend your decision
+if you repackage source that could have been pristine.
+</para>
+<para>
+A repackaged .orig.tar.gz
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+<emphasis role="strong">must</emphasis> contain detailed information how the
+repackaged source was obtained, and how this can be reproduced in the
+<filename>debian/copyright</filename>.  It is also a good idea to provide a
+<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
+building script: debian/rules</ulink>.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="strong">should not</emphasis> contain any file that does not
+come from the upstream author(s), or whose contents has been changed by you.
+<footnote><para> As a special exception, if the omission of non-free files
+would lead to the source failing to build without assistance from the Debian
+diff, it might be appropriate to instead edit the files, omitting only the
+non-free parts of them, and/or explain the situation in a README.Debian-source
+file in the root of the source tree.  But in that case please also urge the
+upstream author to make the non-free components easier seperable from the rest
+of the source.  </para> </footnote>
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="strong">should</emphasis>, except where impossible for legal
+reasons, preserve the entire building and portablility infrastructure provided
+by the upstream author.  For example, it is not a sufficient reason for
+omitting a file that it is used only when building on MS-DOS.  Similarly, a
+Makefile provided by upstream should not be omitted even if the first thing
+your <filename>debian/rules</filename> does is to overwrite it by running a
+configure script.
+</para>
+<para>
+(<emphasis>Rationale:</emphasis> It is common for Debian users who need to
+build software for non-Debian platforms to fetch the source from a Debian
+mirror rather than trying to locate a canonical upstream distribution point).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="strong">should</emphasis> use
+<literal>&lt;packagename&gt;-&lt;upstream-version&gt;.orig</literal> as the
+name of the top-level directory in its tarball.  This makes it possible to
+distinguish pristine tarballs from repackaged ones.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="strong">should</emphasis> be gzipped with maximal compression.
+</para>
+</listitem>
+</orderedlist>
+<para>
+The canonical way to meet the latter two points is to let <literal>dpkg-source
+-b</literal> construct the repackaged tarball from an unpacked directory.
+</para>
+</section>
+
+<section id="changed-binfiles">
+<title>Changing binary files in <literal>diff.gz</literal></title>
+<para>
+Sometimes it is necessary to change binary files contained in the original
+tarball, or to add binary files that are not in it.  If this is done by simply
+copying the files into the debianized source tree,
+<command>dpkg-source</command> will not be able to handle this.  On the other
+hand, according to the guidelines given above, you cannot include such a
+changed binary file in a repackaged <filename>orig.tar.gz</filename>.  Instead,
+include the file in the <filename>debian</filename> directory in
+<command>uuencode</command>d (or similar) form <footnote><para> The file should
+have a name that makes it clear which binary file it encodes.  Usually, some
+postfix indicating the encoding should be appended to the original filename.
+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) &gt; $(file).uuencoded uudecode-file: perl -ne 'print(unpack u, $$_);'
+$(file).uuencoded &gt; $(file) </screen> </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>
+<para>
+Some packages use <command>dbs</command> to manage patches to their upstream
+source, and always create a new <literal>orig.tar.gz</literal> file that
+contains the real <literal>orig.tar.gz</literal> in its toplevel directory.
+This is questionable with respect to the preference for pristine source.  On
+the other hand, it is easy to modify or add binary files in this case: Just put
+them into the newly created <literal>orig.tar.gz</literal> file, besides the
+real one, and copy them to the right place during the build process.
+</para>
+</section>
+
+</section>
+
+<section id="bpp-dbg">
+<title>Best practices for debug packages</title>
+<para>
+A debug package is a package with a name ending in -dbg, that contains
+additional information that gdb can use.  Since Debian binaries are stripped by
+default, debugging information, including function names and line numbers, is
+otherwise not available when running gdb on Debian binaries.  Debug packages
+allow users who need this additional debugging information to install it,
+without bloating a regular system with the information.
+</para>
+<para>
+It is up to a package's maintainer whether to create a debug package or not.
+Maintainers are encouraged to create debug packages for library packages, since
+this can aid in debugging many programs linked to a library.  In general, debug
+packages do not need to be added for all programs; doing so would bloat the
+archive.  But if a maintainer finds that users often need a debugging version
+of a program, it can be worthwhile to make a debug package for it.  Programs
+that are core infrastructure, such as apache and the X server are also good
+candidates for debug packages.
+</para>
+<para>
+Some debug packages may contain an entire special debugging build of a library
+or other binary, but most of them can save space and build time by instead
+containing separated debugging symbols that gdb can find and load on the fly
+when debugging a program or library.  The convention in Debian is to keep these
+symbols in <filename>/usr/lib/debug/path</filename>, where
+<emphasis>path</emphasis> is the path to the executable or library.  For
+example, debugging symbols for <filename>/usr/bin/foo</filename> go in
+<filename>/usr/lib/debug/usr/bin/foo</filename>, and debugging symbols for
+<filename>/usr/lib/libfoo.so.1</filename> go in
+<filename>/usr/lib/debug/usr/lib/libfoo.so.1</filename>.
+</para>
+<para>
+The debugging symbols can be extracted from an object file using objcopy
+--only-keep-debug.  Then the object file can be stripped, and objcopy
+--add-gnu-debuglink used to specify the path to the debugging symbol file.
+<citerefentry> <refentrytitle>objcopy</refentrytitle> <manvolnum>1</manvolnum>
+</citerefentry> explains in detail how this works.
+</para>
+<para>
+The dh_strip command in debhelper supports creating debug packages, and can
+take care of using objcopy to separate out the debugging symbols for you.  If
+your package uses debhelper, all you need to do is call dh_strip
+--dbg-package=libfoo-dbg, and add an entry to debian/control for the debug
+package.
+</para>
+<para>
+Note that the Debian package should depend on the package that it provides
+debugging symbols for, and this dependency should be versioned.  For example:
+</para>
+<screen>
+: libfoo-dbg (= ${binary:Version})
+</screen>
+</section>
+
+</section>
+
+</chapter>
+
diff --git a/beyond-pkging.dbk b/beyond-pkging.dbk
new file mode 100644 (file)
index 0000000..ffbfd3a
--- /dev/null
@@ -0,0 +1,388 @@
+<?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">
+<chapter id="beyond-pkging">
+<title>Beyond Packaging</title>
+<para>
+Debian is about a lot more than just packaging software and maintaining those
+packages.  This chapter contains information about ways, often really critical
+ways, to contribute to Debian beyond simply creating and maintaining packages.
+</para>
+<para>
+As a volunteer organization, Debian relies on the discretion of its members in
+choosing what they want to work on and in choosing the most critical thing to
+spend their time on.
+</para>
+<section id="submit-bug">
+<title>Bug reporting</title>
+<para>
+We encourage you to file bugs as you find them in Debian packages.  In fact,
+Debian developers are often the first line testers.  Finding and reporting bugs
+in other developers' packages improves the quality of Debian.
+</para>
+<para>
+Read the <ulink url="http://www.debian.org/Bugs/Reporting">instructions for
+reporting bugs</ulink> in the Debian <ulink
+url="http://www.debian.org/Bugs/">bug tracking system</ulink>.
+</para>
+<para>
+Try to submit the bug from a normal user account at which you are likely to
+receive mail, so that people can reach you if they need further information
+about the bug.  Do not submit bugs as root.
+</para>
+<para>
+You can use a tool like <citerefentry> <refentrytitle>reportbug</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry> to submit bugs.  It can automate and
+generally ease the process.
+</para>
+<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>
+Utilities like <citerefentry> <refentrytitle>querybts</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry> can also provide you with this
+information (and <command>reportbug</command> will usually invoke
+<command>querybts</command> before sending, too).
+</para>
+<para>
+Try to direct your bugs to the proper location.  When for example your bug is
+about a package which overwrites files from another package, check the bug
+lists for <emphasis>both</emphasis> of those packages in order to avoid filing
+duplicate bug reports.
+</para>
+<para>
+For extra credit, you can go through other packages, merging bugs which are
+reported more than once, or tagging bugs `fixed' when they have already been
+fixed.  Note that when you are neither the bug submitter nor the package
+maintainer, you should not actually close the bug (unless you secure permission
+from the maintainer).
+</para>
+<para>
+From time to time you may want to check what has been going on with the bug
+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>&lt;your-email-addr&gt;</replaceable></literal>.
+</para>
+<section id="submit-many-bugs">
+<title>Reporting lots of bugs at once (mass bug filing)</title>
+<para>
+Reporting a great number of bugs for the same problem on a great number of
+different packages — i.e., more than 10 — is a deprecated practice.  Take
+all possible steps to avoid submitting bulk bugs at all.  For instance, if
+checking for the problem can be automated, add a new check to <systemitem
+role="package">lintian</systemitem> so that an error or warning is emitted.
+</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>
+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
+which several maintainers start filing the same bug report simultaneously.
+</para>
+<para>
+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>.
+</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
+is not forwarded to the bug distribution mailing list.
+</para>
+</section>
+
+</section>
+
+<section id="qa-effort">
+<title>Quality Assurance effort</title>
+<section id="qa-daily-work">
+<title>Daily work</title>
+<para>
+Even though there is a dedicated group of people for Quality Assurance, QA
+duties are not reserved solely for them.  You can participate in this effort by
+keeping your packages as bug-free as possible, and as lintian-clean (see <xref
+linkend="lintian"/> ) as possible.  If you do not find that possible, then you
+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
+for co-maintainers (see <xref linkend="collaborative-maint"/> ).
+</para>
+</section>
+
+<section id="qa-bsp">
+<title>Bug squashing parties</title>
+<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
+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
+modules).
+</para>
+<para>
+The rules for non-maintainer uploads differ during the parties because the
+announcement of the party is considered prior notice for NMU.  If you have
+packages that may be affected by the party (because they have release critical
+bugs for example), you should send an update to each of the corresponding bug
+to explain their current status and what you expect from the party.  If you
+don't want an NMU, or if you're only interested in a patch, or if you will deal
+yourself with the bug, please explain that in the BTS.
+</para>
+<para>
+People participating in the party have special rules for NMU, they can NMU
+without prior notice if they upload their NMU to DELAYED/3-day at least.  All
+other NMU rules apply as usually; they should send the patch of the NMU to the
+BTS (to one of the open bugs fixed by the NMU, or to a new bug, tagged fixed).
+They should also respect any particular wishes of the maintainer.
+</para>
+<para>
+If you don't feel confident about doing an NMU, just send a patch to the BTS.
+It's far better than a broken NMU.
+</para>
+</section>
+
+</section>
+
+<section id="contacting-maintainers">
+<title>Contacting other maintainers</title>
+<para>
+During your lifetime within Debian, you will have to contact other maintainers
+for various reasons.  You may want to discuss a new way of cooperating between
+a set of related packages, or you may simply remind someone that a new upstream
+version is available and that you need it.
+</para>
+<para>
+Looking up the email address of the maintainer for the package can be
+distracting.  Fortunately, there is a simple email alias,
+<literal>&lt;package&gt;@packages.debian.org</literal>, which provides a way to
+email the maintainer, whatever their individual email address (or addresses)
+may be.  Replace <literal>&lt;package&gt;</literal> with the name of a source
+or a binary package.
+</para>
+<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>&lt;package&gt;@packages.qa.debian.org</literal> email
+address.
+</para>
+</section>
+
+<section id="mia-qa">
+<title>Dealing with inactive and/or unreachable maintainers</title>
+<para>
+If you notice that a package is lacking maintenance, you should make sure that
+the maintainer is active and will continue to work on their packages.  It is
+possible that they are not active any more, but haven't registered out of the
+system, so to speak.  On the other hand, it is also possible that they just
+need a reminder.
+</para>
+<para>
+There is a simple system (the MIA database) in which information about
+maintainers who are deemed Missing In Action is recorded.  When a member of the
+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>
+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.
+</para>
+<para>
+The first step is to politely contact the maintainer, and wait a reasonable
+time for a response.  It is quite hard to define reasonable time, but it is
+important to take into account that real life is sometimes very hectic.  One
+way to handle this would be to send a reminder after two weeks.
+</para>
+<para>
+If the maintainer doesn't reply within four weeks (a month), one can assume
+that a response will probably not happen.  If that happens, you should
+investigate further, and try to gather as much useful information about the
+maintainer in question as possible.  This includes:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The echelon information available through the <ulink
+url="https://db.debian.org/">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>
+</listitem>
+<listitem>
+<para>
+The number of packages this maintainer is responsible for, and the condition of
+those packages.  In particular, are there any RC bugs that have been open for
+ages?  Furthermore, how many bugs are there in general?  Another important
+piece of information is whether the packages have been NMUed, and if so, by
+whom.
+</para>
+</listitem>
+<listitem>
+<para>
+Is there any activity of the maintainer outside of Debian?  For example, they
+might have posted something recently to non-Debian mailing lists or news
+groups.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+A bit of a problem are packages which were sponsored — the maintainer is not
+an official Debian developer.  The echelon information is not available for
+sponsored people, for example, so you need to find and contact the Debian
+developer who has actually uploaded the package.  Given that they signed the
+package, they're responsible for the upload anyhow, and are likely to know what
+happened to the person they sponsored.
+</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
+whereabouts of the missing maintainer.  Please Cc: the person in question.
+</para>
+<para>
+Once you have gathered all of this, you can contact
+<email>mia@qa.debian.org</email>.  People on this alias will use the
+information you provide in order to decide how to proceed.  For example, they
+might orphan one or all of the packages of the maintainer.  If a package has
+been NMUed, they might prefer to contact the NMUer before orphaning the package
+— perhaps the person who has done the NMU is interested in the package.
+</para>
+<para>
+One last word: please remember to be polite.  We are all volunteers and cannot
+dedicate all of our time to Debian.  Also, you are not aware of the
+circumstances of the person who is involved.  Perhaps they might be seriously
+ill or might even have died — you do not know who may be on the receiving
+side.  Imagine how a relative will feel if they read the e-mail of the deceased
+and find a very impolite, angry and accusing message!
+</para>
+<para>
+On the other hand, although we are volunteers, we do have a responsibility.  So
+you can stress the importance of the greater good — if a maintainer does not
+have the time or interest anymore, they should let go and give the package to
+someone with more time.
+</para>
+<para>
+If you are interested in working in the MIA team, please have a look at the
+README file in /org/qa.debian.org/mia on qa.debian.org where the technical
+details and the MIA procedures are documented and contact
+<email>mia@qa.debian.org</email>.
+</para>
+</section>
+
+<section id="newmaint">
+<title>Interacting with prospective Debian developers</title>
+<para>
+Debian's success depends on its ability to attract and retain new and talented
+volunteers.  If you are an experienced developer, we recommend that you get
+involved with the process of bringing in new developers.  This section
+describes how to help new prospective developers.
+</para>
+<section id="sponsoring">
+<title>Sponsoring packages</title>
+<para>
+Sponsoring a package means uploading a package for a maintainer who is not able
+to do it on their own, a new maintainer applicant.  Sponsoring a package also
+means accepting responsibility for it.
+</para>
+<para>
+New maintainers usually have certain difficulties creating Debian packages —
+this is quite understandable.  That is why the sponsor is there, to check the
+package and verify that it is good enough for inclusion in Debian.  (Note that
+if the sponsored package is new, the ftpmasters will also have to inspect it
+before letting it in.)
+</para>
+<para>
+Sponsoring merely by signing the upload or just recompiling is <emphasis
+role="strong">definitely not recommended</emphasis>.  You need to build the
+source package just like you would build a package of your own.  Remember that
+it doesn't matter that you left the prospective developer's name both in the
+changelog and the control file, the upload can still be traced to you.
+</para>
+<para>
+If you are an application manager for a prospective developer, you can also be
+their sponsor.  That way you can also verify how the applicant is handling the
+'Tasks and Skills' part of their application.
+</para>
+</section>
+
+<section id="s7.5.2">
+<title>Managing sponsored packages</title>
+<para>
+By uploading a sponsored package to Debian, you are certifying that the package
+meets minimum Debian standards.  That implies that you must build and test the
+package on your own system before uploading.
+</para>
+<para>
+You cannot simply upload a binary <filename>.deb</filename> from the sponsoree.
+In theory, you should only ask for the diff file and the location of the
+original source tarball, and then you should download the source and apply the
+diff yourself.  In practice, you may want to use the source package built by
+your sponsoree.  In that case, you have to check that they haven't altered the
+upstream files in the <filename>.orig.tar.gz</filename> file that they're
+providing.
+</para>
+<para>
+Do not be afraid to write the sponsoree back and point out changes that need to
+be made.  It often takes several rounds of back-and-forth email before the
+package is in acceptable shape.  Being a sponsor means being a mentor.
+</para>
+<para>
+Once the package meets Debian standards, build and sign it with
+</para>
+<screen>
+-buildpackage -k<replaceable>KEY-ID</replaceable>
+</screen>
+<para>
+before uploading it to the incoming directory.  Of course, you can also use any
+part of your <replaceable>KEY-ID</replaceable>, as long as it's unique in your
+secret keyring.
+</para>
+<para>
+The Maintainer field of the <filename>control</filename> file and the
+<filename>changelog</filename> should list the person who did the packaging,
+i.e., the sponsoree.  The sponsoree will therefore get all the BTS mail about
+the package.
+</para>
+<para>
+If you prefer to leave a more evident trace of your sponsorship job, you can
+add a line stating it in the most recent changelog entry.
+</para>
+<para>
+You are encouraged to keep tabs on the package you sponsor using <xref
+linkend="pkg-tracking-system"/> .
+</para>
+</section>
+
+<section id="s7.5.3">
+<title>Advocating new developers</title>
+<para>
+See the page about <ulink
+url="http://www.debian.org/devel/join/nm-advocate">advocating a prospective
+developer</ulink> at the Debian web site.
+</para>
+</section>
+
+<section id="s7.5.4">
+<title>Handling new maintainer applications</title>
+<para>
+Please see <ulink
+url="http://www.debian.org/devel/join/nm-amchecklist">Checklist for Application
+Managers</ulink> at the Debian web site.
+</para>
+</section>
+
+</section>
+
+</chapter>
+
diff --git a/debian/TODO b/debian/TODO
new file mode 100644 (file)
index 0000000..4698bef
--- /dev/null
@@ -0,0 +1,21 @@
+NMU -- sec "Source NMUs and the Bug Tracking System" should talk about
+changelog entries -- dinstall works that out depending on whether the
+maintainer in the control and changelog match.
+
+db/LDAP thing email gate @
+ http://www.debian.org/Lists-Archives/debian-devel-9912/msg00627.html
+
+critique from herzog:
+http://www.debian.org/vote/2002/platforms/raphael
+
+<aph> Robot101: do you have a URL describing new incoming system?
+<Robot101> http://lists.debian.org/debian-devel-announce/2002/debian-devel-announce-200202/msg00006.html
+
+<buxy> we'll be able to include a blurb about the PTS in the Resources part
+<buxy> we just need to wait the text from the guy who proposed his help
+<buxy> We need to think about other "simplifications" too
+<buxy> for example, all that stuff about upload queues is mostly useless
+
+http://people.debian.org/~walters/descriptions.html
+  Colin Walters approved
+
diff --git a/debian/changelog b/debian/changelog
new file mode 100644 (file)
index 0000000..acadb63
--- /dev/null
@@ -0,0 +1,1392 @@
+developers-reference (3.3.9) unstable; urgency=low
+
+  * Packaging changes:
+    - bump standards-version to 3.7.2 (no change)
+    - fix debian/copyright
+    - move debhelper to Build-Depends.
+    - add pdf for French version.
+  * Document changes to stable release management. Closes: #414291
+  * Debconf error templates no longer discouraged. Thanks,
+    Christian Perrier. Closes: #427832
+  * Keyring now uses RT. Closes: #428846
+  * Document -dbg-packages within BPs. Thanks, Joey Hess. Closes: #420540
+  * NMUs now also close bugs. Thanks, Lucas Nussbaum. Closes: #419507
+  * Fix documentation about gender neutral. Closes: #384178
+  * Fix typo. Closes: #405453
+  * More details on how to write documentation. Thanks, Josh Triplett.
+    Closes: #422750
+  * Add XS-Vcs-*. Thanks to Stefano Zacchiroli. Closes: #391023
+  * Small brushup to debconf description. Thanks, Thomas Huriaux.
+    Closes: #401415
+  * Document Team-Maintainence better. Thanks, Lucas Nussbaum.
+    Closes: #410159
+  * Add link to more removal ressources. Thanks, Adam D. Barratt,
+    Justin Pryzby. Closes: #412757, #356720
+  * Repacking source packages need to be documented in copyright.
+    Thanks, Russ Allbery. Closes: #413320
+  * Better describe version of debian native packages NMUs. Closes: #405818
+
+ -- Andreas Barth <aba@not.so.argh.org>  Sat, 16 Jun 2007 11:41:41 -0600
+
+developers-reference (3.3.8) unstable; urgency=low
+
+  * mia-history is replaced by mia-query. Thanks, Christoph Berg.
+    Closes: #350792
+  * fix missing quite. Thanks, Frank Küster. Closes: #365994
+  * use gnugp instead of gpg. Thanks, Justin Pryzby, Jon Dowland.
+    Closes: #376411
+  * better destinction between maintainer and developer. Thanks for
+    the suggestion to Colin Tuckley. Closes: #380458
+  * irc.d.o points to oftc. Thanks, Christoph Biedl, Jon Dowland.
+    Closes: #382721
+  * Bugs are now always closed thanks to version tracking.
+    Closes: #339552, #353447, #376199
+  * Clarify what "a conflicts b" means in testing migration. 
+    Closes: #361311
+  * Packages in testing disappear if they're removed from unstable.
+    Thanks, Frank Küster, Al Stone. Closes: #365993
+  * Document only the most recent changelog entry is used. Thanks
+    to Kevin Glynn to the suggestion. Closes: #374738
+  * Add more tools for reverse depends. Close: #376582
+  * delayed-queue on gluck is uploaded more often now. Closes: #397907
+  * stop using capitals, minor fixes, language fixes.
+    Thanks, Thijs Kinkhorst, Colin Tuckley, Russ Allbery.
+    Closes: #368046, #378929, #361744
+  * add CVE Ids to your changelog. Closes: #376961
+  * add reasoning why debconf questions shouldn't be longer than
+    20 lines. Thanks, Thijs Kinkhorst, Christian Perrier, Russ Allbery.
+    Closes: #382477
+  * section changing needs re-uploading orig.tar.gz.
+    Thanks, Adam D. Barratt. Closes: #387154
+  * binary files in diffs could be en/decoded with perl.
+    Thanks, Frank Küster. Closes: #397786
+  * Add pointer to new-reject-FAQ. Closes: #324967
+  * Hint to dd-list/whodepends. Closes: #353874
+  * Don't use too generic mail ids. Closes: #355725
+  * pts/summary is actually used. Thanks, Holger Levsen. Closes: #387108
+  * clarify that one should append the NMU-diff to a bug. Closes: #394033
+  * more detailed instructions on binary package removals.
+    Closes: #356643
+
+  * Frédéric Bothamy
+    - French translation updated to version 3.3.8
+
+ -- Andreas Barth <aba@not.so.argh.org>  Sat, 11 Nov 2006 10:55:44 -0700
+
+developers-reference (3.3.7) unstable; urgency=low
+
+  * Andreas Barth:
+    - adjust information about distributions with reality.
+    - add note on alioth accounts. Thanks, Phillip Kern. Closes: #306630
+    - correct manpage section of dpkg-scanpackages. Closes: #297069
+    - fix RFC 2440 URL. Closes: #308103
+    - add $arch@buildd information. Closes: #295483
+    - link to keyring.d.o for key replacement. Thanks, Martin Michlmayr.
+      Closes: #298016
+    - add information about Packages-arch-specific. Thanks, Frank Küster.
+      Closes: #302000
+    - add hint about LWN subscription. Thanks, Martin Michlmayr.
+      Closes: #299217
+    - more about debconf-style translation. Thanks, Christian Perrier.
+      Closes: #309502
+    - non-us discontinued.
+    - document nmu changes wrt version tracking. Thanks, Justin Pryzby.
+      Closes: #341197
+    - fix spelling issues. Thanks to various people.
+      Closes: #336146, #326857, #338660
+    - update menu policy helpers. Thanks, Florian Ernst. Closes: #340024
+    - send mia-mail to mia@qa. Thanks, Adam D. Barratt. Closes: #341568
+    - Joerg Jaspert is now freenode contact. Closes: #344303
+    - give a clearer description of the gpg v4-key issues. Thanks,
+      Martin Michlmayr and Peter Palfrader. Closes: #317411
+    - more verbose about Homepage. Closes: #339826
+    - add sarge and etch. Closes: #327682
+    - document severity of RoM-request bugs. Closes: #305947
+    - update FSF address. Closes: #334820
+    - fix P-a-s link. Closes: #341195
+    - reflect binNMU changes. Closes: #349493
+    - new security upload queue. Closes: #352749
+    - fix experimental's sources.list entry. Closes: #347229
+    - remove deprecated "Closes:..." to ACK NMU bug fixes. Closes: #353447
+    - when resigning, gpg-sign your mail. Closes: #348160
+    - make pristine source and repackaged origtargz anchors work.
+      Closes: #351255
+    - same number of RC bugs is ok. Closes: #351944
+    - dpkg-source doesn't keep permissions. Thanks, Enrico Zini.
+      Closes: #306120
+    - also mention aspell. Closes: #320981
+
+  * Frédéric Bothamy
+    - French translation updated to version 3.3.7, proofread by Bernard Adrian
+  
+ -- Andreas Barth <aba@not.so.argh.org>  Sun, 09 Apr 2006 11:31:52 -0600
+
+developers-reference (3.3.6) unstable; urgency=low
+
+  * Andreas Barth
+    - closes: and NMUs/experimental uploads. Closes: #284714
+    - madison is on merkel.
+    - more gender-neutral. Closes: #290583, #290584, #263114
+    - explain current incoming. Closes: #290019
+    - remove broken sponsoring URL. Closes: #291698
+    - add handling hints about orig.tar.gz. Thanks, Frank. Closes: #278524
+    - duplicate bug reports should be merged. Closes: #285381
+    - if you're on vacation, please check whether someone needs keysigning.
+      Closes: #285458
+    - freenode has developer cloacks. Closes: #285687
+    - cleaned up uploaders / maintainer field
+    - explain how dak detects NMUs. Closes: #292354
+    - add "mass" to lots of bugs. Closes: #292946
+    - sync NM rules with reality.
+  * Frédéric Bothamy
+    - French translation updated to version 3.3.6
+
+ -- Andreas Barth <aba@not.so.argh.org>  Sun, 23 Jan 2005 16:08:49 -0700
+
+developers-reference (3.3.5) unstable; urgency=low
+
+  * Andreas Barth
+    - uploads to more than one dist are not possible.
+    - updated upload queues. Closes: #235213
+    - updated URL of vanilla rules files. Closes: #237557, #252048
+    - please speak with stable RM before uploading to stable. Closes: #261464
+    - information on wnpp usage synced with wnpp. Closes: #255298
+    - spelling, grammer fixes.
+      Closes: #202444, #202499, #203202, #203378, #221902, #226208
+    - add hint about partitial key id. Closes: #243968
+    - spohr is restriced, and also ftp-master. Closes: #255814
+    - bpp: Hint about locale generation as non-root. Closes: #208021
+    - bpp: deborphan-compliant transition packages. Closes: #183654
+    - add myself to uploaders.
+    - add chapter about i10n. Closes: #208156
+    - add information about dchroot. Closes: #211845
+    - add information about NEWS.Debian. Closes: #212402
+    - add information about mia-database. Closes: #213961
+    - add link to debian-mentors FAQ.
+    - add verbose information about the package description. Closes: #214792
+    - add hint about -v<version> to experimental. Closes: #232930
+    - update information about yada. Closes: #217956
+    - urgency is sticky. Closes: #261914
+    - updated information about testing distribution. Closes: #266649.
+    - rewrote the NMU section, and
+      + made the possible severities of "target bugs" clearer. Closes: #233088.
+      + mention QA uploads. Closes: #202416.
+      + add -B for binNMUs, and local debsign usage. Closes: #208839.
+      + warning about breaking all-packages by binNMU. Closes: #213348.
+    - add information about gpg usage. Closes: #175815.
+    - make key replacement instructions more details. Closes: #275921
+    - typo and language fixes. Thanks, Era Eriksson. Closes: #277576
+    - add hints about debconf templates from Christian Perrier.
+  * Matt Zimmerman
+    - Security uploads get urgency=high
+    - Be even more explicit about not uploading security updates
+  * Frédéric Bothamy
+    - French translation updated to version 3.3.5
+
+ -- Andreas Barth <aba@not.so.argh.org>  Mon, 22 Nov 2004 19:07:26 +0100
+
+developers-reference (3.3.4) unstable; urgency=low
+
+  * Josip Rodin:
+    - fixed language in the PTS section, prompted by a patch from
+      Romain FRANCOISE, thank you; closes: #197741
+    - updated the mailing lists section (again)
+    - documented Alioth, somewhat
+  * Frédéric Bothamy
+    - French translation updated to version 3.3.3 (more or less)
+    - proofread by Patrice Karatchentzeff
+  * Matt Zimmerman
+    - Don't upload security updates directly to stable
+    - Always include an external reference in security changelog entries
+    - Be careful not to re-use a version number in security uploads
+    - More explicit instructions about what is appropriate for a security
+      upload
+
+  * Adam Di Carlo
+    - replace <!entity...> with <!ENTITY...> and other SGML hygenics
+    - build refinements
+    - Release this package as is to flush changes between June and now.
+      Yes, its been an age between releases here, for which I apologize.
+      Since CVS upstream for this package is back, I'm working on closing
+      bugs in this package now, I just wanted to get it out as is before I
+      started.
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 29 Feb 2004 14:09:48 -0500
+
+developers-reference (3.3.3) unstable; urgency=low
+
+  * Frédéric Bothamy
+    - corrections by Michel Grentzinger
+  * Raphaël Hertzog
+    - updated documentation concerning the PTS
+    - added a paragraph about the PTS web interface
+    - documented how to add custom news item in the PTS
+  * Matt Zimmerman
+    - updates and clarifications to instructions for security bugs
+    - deprecate uploads to stable for security fixes, reference
+      section on security bugs; closes: #196516
+    - use dpkg-buildpackage -B to test binary-arch, not -b;
+      closes: #196555
+  * Adam Di Carlo
+    - Sec "Managing sponsored packages": remove unnecessary 'debsign' cmd;
+      closes: #192417
+    - fix debconf-devel(7) man page section; closes: #189512
+    - Sec "Responding to bugs": mention what FTBFS means; closes: #186605
+    - Sec "Distribution directories" renamed "Distributions"
+    - Sec "The testing distribution" moved under Sec "Distribution
+      directories" and renamed "More information about the testing
+      distribution"
+    - Secs "Uploads to {stable,testing-proposed-updates}" retitled to make
+      it clear these are special cases
+    - Sec "Uploading to ftp-master": xref to "Delayed incoming"; 
+      closes: #195997
+    - check compliance with Policy version 3.5.10
+
+ -- Adam Di Carlo <aph@debian.org>  Mon, 16 Jun 2003 04:08:29 -0400
+
+developers-reference (3.3.2) unstable; urgency=low
+
+  * Frédéric Bothamy:
+    - French translation updated to version 3.3.1
+    - proofread by Philippe Batailler and Patrice Karatchentzeff
+  * Adam Di Carlo:
+    - French translation requires debiandoc-sgml 1.1.76 or better
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 18 Apr 2003 09:48:59 -0400
+
+developers-reference (3.3.1) unstable; urgency=low
+
+  * Josip Rodin:
+    - package description said it contained French and Japanese, fixed,
+      closes: #182614
+    - Sec "Experimental": sources.list entries
+    - Sec "Basic rules for [mailing list] use": cosmetic, link to this sec
+    - Sec "Handling bugs": retitle and expand section
+  * Adam Di Carlo:
+    - more improvements to package synopsis and description
+    - the synopsis formula changed to either
+       <package-name> is a <synopsis>
+      or
+       <package-name> is <synopsis>
+      or
+       <package-name> are <synopsis>
+      closes: #182956
+    - the synopsis itself should not start with an article
+    - Sec "Best practices for debian/control": expand intro
+    - fix doc-check URL; closes: #187144
+    - Sec "Multiple binary packages": fix awkward wording about vim source
+      package; closes: #187143
+
+ -- Adam Di Carlo <aph@debian.org>  Fri,  4 Apr 2003 14:26:52 -0500
+
+developers-reference (3.3) unstable; urgency=low
+
+  * Frédéric Bothamy:
+    - French translation updated to version 3.2.2 (more or less)
+    - proofread by Philippe Batailler
+  * Raphaël Hertzog:
+    - added "ddtp" keyword in the PTS documentation
+  * Josip Rodin:
+    - split out the doc-files per language, closes: #177448
+    - shuffled stuff around in the packages chapter
+    - added a section describing how to handle large amounts of
+      architecture-independent data bundled with programs
+    - added best practices on debian/changelog files, based on a patch
+      kindly provided by Daniel Kobras, closes: #166388
+    - described debdiff and dpkg-depcheck, and linked to them from the
+      right places in the document, closes: #172897
+    - describe the current practice in writing synopsis lines,
+      closes: #174161
+  * Adam Di Carlo:
+    - update (c) year
+    - convert to debhelper (compat mode 4); maintainer scripts no longer
+      needed
+    - split -ja and -fr versions out into separate packages
+    - top-level makefile deletes targets on error; clean is cleaner
+    - replace the manual debian/control processing to show the document's
+      table of contents (TOC) with a new script 'debian/tocsubstvars';
+      note that the TOC displayed in the developers-reference-{fr,ja}
+      package descriptions are in English until UTF8 control files are
+      allowed; proper escaping of single quotes here requires newest
+      debhelper
+    - editorial changes on material added in this version
+    - reorder "Best Packaging Practices" a bit
+    - rework "Best practices for debian/control" based on contributions
+      from Colin Walters, Branden Robinson, Sebastian Rittau and others;
+      closes: #139957, #108416
+    - primary author is developers-reference@packages.debian.org; remove
+      emails from other authors to prevent spam and confusion
+
+ -- Adam Di Carlo <aph@debian.org>  Mon, 24 Feb 2003 13:29:07 -0500
+
+developers-reference (3.2.2) unstable; urgency=low
+
+  * Josip Rodin:
+    - slightly rewrote and updated links in the mirrors section
+  * Adam Di Carlo:
+    - Policy compliance checked and updated to 3.5.8, no changes needed
+    - TODO: remove some tasks which are done
+    - ship README-contrib and TODO in the doc dir
+    - Sec "Upstream home page": some revisions based on discussion on
+      policy list
+    - Sec "Documentation" added under Sec "Common packaging situations"
+      for best practices for documentation
+    - Add tools entries for autotools-dev, dpkg-repack, alien, debsums;
+      new Sec "Documentation and information", add entries there for
+      debview, debiandoc-sgml, debian-keyring; we believe this manual now
+      covers all of the established, general Debian maintainer tool
+      packages
+    - spell-checking pass
+
+ -- Adam Di Carlo <aph@debian.org>  Thu, 12 Dec 2002 13:45:23 -0500
+
+developers-reference (3.2.1) unstable; urgency=low
+
+  * Adam Di Carlo:
+    - Sec "Best practices for debian/control" added, Sec "Writing useful
+      descriptions" moved under there
+    - Sec "Upstream home page" added in debian/control section
+    - Sec "Miscellaneous advice" empty, removed
+    - Sec "Overview of maintainer tools": tools now categorized into
+      subgroups; do cross-linking from this section into other parts of
+      the document where these tools are discussed
+    - Sec "Overview of maintainer tools": add entries for sbuild,
+      build-essential, linda; improved entries for pbuilder, devscripts
+    - Sec "Tools for porters" renamed and readapted to "Porting
+      infrastructure and automation"; move tool discussion down to the
+      appendix; improve Sec "buildd" a bit
+    - README-contrib added giving information for authors, contributors,
+      and translators
+    - eliminate the ByHand stuff, I'm pretty sure it's not needed now
+      with the DDP builder process, or if it is needed, it's a probably
+      that can be fixed by DDP folks
+    - stop shipping SGML source -- use 'apt-get source developers-reference'
+      after all, this is supposed to be a binary package, right?
+    - simply PS and PDF building rules
+  
+ -- Adam Di Carlo <aph@debian.org>  Mon,  9 Dec 2002 03:04:19 -0500
+
+developers-reference (3.2) unstable; urgency=low
+
+  * Josip Rodin:
+    - merged a bit misplaced lintian-reports section within the lintian
+      section and adjusted links
+    - added the missing description of dh-make and adjusted links
+  * Adam Di Carlo:
+    - ChangeLog attribution updates
+    - fix typos, closes: #171781
+    - expand the doc-base abstract and authors
+    - Ch "Packaging Practices" rewritten intro
+    - Sec "Packaging tools and common cases" renamed to "Best Practices
+      for debian/rules", and write an intro
+    - Sec "Helper scripts" in practices section rewritten, giving
+      arguments for and against debhelper, mostly for :)
+    - Sec "Package with multiple patches" renamed to "Patching source
+      versus patching at build time" and rewritten
+    - Sec "Multiple binary packages" rewritten
+    - Sec "Handling debconf translations" moved under an
+      "Internationalization" section, and some edits
+    - Sec "Internationalized Documentation" added under Sec
+      "Internationalization"
+    - Sec "Specific packaging practices" renamed to "Common packaging situations"
+    - Sec "Packages using autoconf/automake" rewritten
+    - Sec "Configuration management" moved forward in practices chapter
+    - Sec "Other specific packages" renamed to "Specific types of
+      packages", add info for SGML/XML and Lisp packages
+    - Sec "Writing useful descriptions" heavily edited
+    - Sec "Best practices for maintainer scripts" added, special credit
+      here to Charles Briscoe-Smith for work dating back to 1998; include
+      a POSIX shell snippet showing how to check if a command is the PATH,
+      closes: #150384
+    - Apdx "Overview of Debian Maintainer Tools": remove debget, it's
+      rather useless and broken
+    - normalize up-casing on sections, which should only up-case proper
+      names and the first word
+    - new 'translation-status' script to check status of translations,
+      adapted from doc-check in boot-floppies, source pkg only --
+      oh my, French translation is 54 CVS revisions behind, and Japanese
+      is 108 behind
+    - postinst: don't set /usr/doc symlink, aesthetics
+    - prerm: don't use 'command -v', it's not POSIX
+    - rules: produce md5sums file; break out a 'test' target
+
+ -- Adam Di Carlo <aph@debian.org>  Sat,  7 Dec 2002 02:28:06 -0500
+
+developers-reference (3.1.2) unstable; urgency=low
+
+  * Josip Rodin:
+    - DDP publishing update
+  * Adam Di Carlo:
+    - doc-base file includes French and Japanese files
+    - debsign invocation was slightly wrong, closes: #170523
+    - Sec "Handling debconf translations", updates from Martin Quinson
+      for po-debconf with minimal editorial changes, closes: #169007
+
+ -- Adam Di Carlo <aph@debian.org>  Wed, 27 Nov 2002 21:16:30 -0500
+
+developers-reference (3.1.1) unstable; urgency=low
+
+  * Josip Rodin:
+    - updated IRC stuff, thanks to Ben Armstrong, closes: #161403
+    - fixed/updated/extended stuff about bugs, hoping to address the
+      issue of people abusing the changelog bug closing feature
+  * Raphaël Hertzog:
+    - added myself as co-author
+    - fix a typo in Sec "Collaborative maintenance", closes: #161488
+  * Matt Zimmerman:
+    - updated security information, merging in Joey's stuff from the
+      Security Team FAQ and various updates and clarifications
+  * Adam Di Carlo
+    - fix some bad URLs, closes: #168357
+    - fix a grammar typo, closes: #166098
+
+ -- Adam Di Carlo <aph@debian.org>  Tue, 12 Nov 2002 23:15:03 -0500
+
+developers-reference (3.1) unstable; urgency=low
+
+  * Raphaël Hertzog:
+    - Corrected several errors with &mdash;
+    - Applied patch from Peter Palfrader, correcting
+      the URL for the Debian Voting Information page. closes: #150427
+    - Applied patch from Matej Vela, dpkg-buildpackage does no more
+      require -sa for version -0.1. closes: #150861
+    - Applied the reformulations proposed by David Kimdon. closes: #150572
+    - Applied the patch of Matt Zimmerman. Thanks Matt! closes: #145287
+    - Added the explanation about how to replace an .orig.tar.gz.
+      closes: #150392
+    - Mostly deleted the paragraph about security upload in the
+      section explaining source NMU. Just added a link to point to
+      "Handling security-related bugs". closes: #159935
+    - Added a link to the Technical Committee web page (in the "Bug
+      housekeeping" section). closes: #151365
+    - Explain uploads to testing-proposed-updates, mentions briefly
+      stable-security and testing-security. closes: #149666
+      Removed the comment about uploads to frozen.
+    - Documented the "Developer's packages overview" web portal.
+      closes: #158650
+    - Added a reference to debian-l10n-english in "Writing useful
+      descriptions". closes: #158609
+    - Added a Best Packaging Practice section for "Packages using
+      autoconf/automake". closes: #158045
+    - Documented associated features to db.debian.org like SSH key
+      replication and *.debian.net DNS entry. closes: #155389
+    - Added a section about "Bug Squashing Parties".
+  * Josip Rodin:
+    - removed obsolete, needless dupload variables
+    - applied linguistic fixes from David Kimdon, closes: #150572
+    - random proofreading, mostly changing he -> they
+    - added people.d.o and non-us.d.o to the Debian servers section, and
+      mostly rewrote it to exclude real machine names and be better organized
+    - updated the mailing lists section
+  * Adam Di Carlo
+    - debian/changelog: remove obsolete Emacs variables
+    - editorial review of the changes above, minor tagging changes,
+      spelling fixes
+
+ -- Adam Di Carlo <aph@debian.org>  Tue, 10 Sep 2002 21:57:41 -0400
+
+developers-reference (3.0) unstable; urgency=low
+
+  * Adam Di Carlo:
+    - welcome Manoj Srivastava as a co-maintainer
+    - welcome Raphael Hertzog as a co-maintainer
+
+    - new Chapter "Resource for Debian Developers", incorporating
+      the former chapters
+       Ch "Mailing Lists, Servers, and Other Machines"
+       Ch "The Debian Archive"
+  
+    - new Chapter "Managing Packages", incorporating former chapters
+       Ch "Package uploads"
+       Ch "Non-Maintainer Uploads (NMUs)"
+       Ch "Porting and Being Ported"
+       Ch "Moving, Removing, Renaming, Adopting, and Orphaning Packages"
+       Ch "Handling Bugs" (retitled "Handling package bugs")
+       Sec "Bug housekeeping" (new section, some parts stubbed out)
+     
+    - new Chapter "Beyond Packaging" recommends ways to contribute
+      to Debian beyond issues of package maintenance; incoporates
+      Ch "Interaction with Prospective Developers", retitled to
+          Sec "Interacting with Prospective Debian Developers"
+      Sec "Submitting Bugs", renamed to "Reporting Bugs"
+      Sec "QA" moved here from old Sec "Quality Assurance effort"
+      Sec "Dealing with unreachable maintainers"
+
+    - Sec "The Developers Database" added under Resources
+    - new Sec "Collaborative Maintenance" concerning multiple maintainers
+      for one package
+
+    - Sec "Getting started": add link to New Maintainers' Guide
+    - Sec "Debian Mentors" renamed to "Debian Mentors and Sponsors",
+      we add some info on sponsoring; also in Sec "Sponsoring packages"
+    - Section's first word capitalized, rest are normal case
+    - purge a reference to the Packaging Manual; closes: #145039
+    - misc. cross-referencing with new or moved sections
+    - change some literal quotes to &lsquo;, &rdquo;, etc.
+    - tagging improvements: replace <tt> with <file> for files and
+      directories; since <tt><var> and <example><var> doesn't look right,
+      work-around with &lt;...&gt;
+    - entity'ize master.debian.org, us-upload-dir, non-us-upload-dir
+    - update copyright date
+    - some simplifications on the TeX suffix rule
+    - spell check and grammar corrections
+    - s/GPG/GnuPG/
+
+  * Raphael Hertzog:
+    - changed -e by -m in the dpkg-buildpackage command line example;
+      closes: #110310
+    - clarify wording between "porter upload", "binary-only NMU", "simple
+      recompile"; closes: #102626
+    - extended "removing a package"; closes: #135560
+    - Ch "Best Packaging Practices": new chapter, including new
+      Sec "Writing useful descriptions" as a first entry in that
+      chapter; closes: #53109, #129848
+    - indicate that the list of subsections is defined in the policy;
+      closes: #123586
+    - removed some cruft in `Announcing package uploads'
+    - document the testing scripts; closes: #129445
+    - explain how to reassign/close bugs of removed packages; 
+      closes: #130255
+    - updates the note about software subject to US patents; 
+      closes: #142798
+    - new Section "Contacting other maintainers" under "Beyond packaging"
+      Document the package@packages.debian.org alias; closes: #114553
+    - new Section "Package's information" under Resources
+      Document http://packages.debian.org/<package>,
+      http://bugs.debian.org/<package> and the madison utility
+    - Sec "Reporting bugs": added http://bugs.debian.org/from:email@isp.com
+    - Sec "Handling bugs": added http://bugs.debian.org/login@debian.org
+    - Sec "The Incoming system" in "Resources", describe how it works and
+      also speak of the DELAYED directory; closes: #135562, #136774
+    - spelling fixes
+    - Sec "Developer Database": added a sentence about finger
+      login@debian.org
+    - update the total number of packages and the example directory tree
+      of a Debian archive
+    - updated the list of available architectures.
+    - commented out the "Subsections" section since it will RSN have nothing
+      to with the Debian archive. It's just a generic information field
+      of the package and nothing more.
+    - added more incentive to use experimental since it doesn't cause
+      any pain to the ftpmasters.
+    - Sec "When to do a source NMU": updated the NMU "protocol" and suggest
+      the use of the delayed queue.
+    - new Section "Acknowledging the NMUs" to explain the need to integrate
+      the changes introduced by NMUs. Insists on the fact that one shouldn't
+      be upset by a NMU.
+    - stubbed in new Section "Collaborative maintenance"
+    - stubbed in new Section "The Package Tracking System"
+    - Sec "The Package Tracking System": filled with content from
+      Francesco Paolo Lovergine, heavily updated by myself
+    - new Section "Managing sponsored packages" contributed by
+      Francesco Paolo Lovergine, slightly updated by myself
+    - new Sec "Bug housekeeping"; closes: #39519
+    - new Sec "Voting"
+    - new Sec "Documentation"
+    - added Sec "IRC channels" in the Resources chapter
+    - added Sec "pbuilder" in the appendix. Mention it in the section
+      "Being kind to porter" too
+    - extended Sec "devscripts" with info about "bts" and "uscan"
+    - completed Sec "Helper scripts"
+    - completed Sec "Package with multiple patches",
+      "Multiple binary packages", "Libraries", "Other specific packages",
+      "The wise use of debconf" -- all those are quite simplistic, they
+      can be improved
+    - integrated Sec "Handling debconf translations" contributed by
+      Denis Barbier -- thanks, Denis!
+
+  * Antoine Hulin:
+    - update French translation
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 14 Jun 2002 01:18:19 -0400
+
+developers-reference (2.11) unstable; urgency=low
+
+  * Antoine Hulin:
+    - some grammar corrections
+    - update French translation
+  * Martin Michlmayr:
+    - changes in upload situation, not possible to remove from Incoming
+      anymore; closes: #135559
+    - also talk about dput a tiny bit
+  * Adam Di Carlo:
+    - Ch "Overview of Debian Maintainer Tools":
+      - improve the intro
+      - Charles Briscoe-Smith deprecates yada (I think new maintainers of
+        that would be welcome)
+      - debconf-doc mentioned for debconf
+      - debhelper: don't talk about debmake; mention how to get info on the dh-* pkgs
+      - dput: new section, closes: #129378
+      - debootstrap: new section, closes: #129377
+      - dpkg-dev-el: new section
+      - other minor wording changes
+    - Sec "Mailing Lists": where to find private archives, closes: #96780
+    - Ch "Package uploads":
+      - new Sec "Adding an entry to debian/changelog"
+      - rename Sec "Announcing new packages" to "New packages"
+    - crypto is in main, non-US is for patent restrictions, so:
+      - excise some text from "Registering as a Debian developer"
+      - changes in Sec "Uploading to ftp-master"
+      - changes in Sec "Uploading to non-US"
+  * old bugs closed out, closes: #110573
+
+ -- Adam Di Carlo <aph@debian.org>  Sun,  7 Apr 2002 23:34:08 -0700
+
+developers-reference (2.10.0) unstable; urgency=low
+
+  * from Martin Michlmayr
+    - update the "Applying to Become a New Maintainer" section, with
+      review by Raphael Hertzog, closes: #133965
+    - bugs closed in NMUs should uses 'closes' changelog entries,
+      closes: #133951
+    - developers are not required to subscribe to debian-private
+      closes: #133955
+    - some suggestions on places to use the proper term, Debian GNU/Linux,
+      closes: #133953
+    - fix some typos, closes: #133956
+  * Adam Di Carlo:
+    - frozen doesn't exist anymore, just testing; note, however, that
+      there is a way to upload to 'woody-proposed-updates' -- if I can
+      find some description of that, I'll document it; closes: #133948
+    - minor build tweaks
+    - minor cosmetics
+    - isolate a few more language-independent bits
+  * from Chris Tillman
+    - change /usr/doc to /usr/share/doc, and typo in debian/copyright,
+      closes: #126924
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 24 Feb 2002 14:46:46 -0500
+
+developers-reference (2.9.0) unstable; urgency=low
+
+  * Josip Rodin: 
+    - created a new subsection about uploading to stable, and elaborated
+      about that subject
+    - removed a stray sentence about stable from the paragraph about
+      security uploads (which apply to all distributions equally)
+    - replaced the nonexistent term "Security Manager" with "security officer"
+    - uploading to stable and unstable is deprecated; updated the section
+      about the experimental distribution; other fixes in the section
+      talking about uploading to distributions
+    - better organize some subsections in the section about package uploads
+    - replaced some bogus <ftppath>s with <tt>s
+    - noted how there is an upload queue on pandora, too
+  * Antoine Hulin:
+    - French translation updated
+  * Adam Di Carlo:
+    - normalize '--' as &mdash; for prettier output
+    - integrate changes from James Troup, part of #102626
+    - typo fix thanks to Mark Hodge
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 21 Oct 2001 01:03:01 -0400
+
+developers-reference (2.8.8) unstable; urgency=low
+
+  * from Josip Rodin:
+    - a few more strong words about sponsoring
+    - started a        new chapter about the relationship between old and new
+      developers
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 20 Jul 2001 17:53:47 -0400
+
+developers-reference (2.8.7) unstable; urgency=low
+
+  * French updates
+  * fix a typo in a link
+  * dpkg-buildpackage -m<addr> flag was changed for -e<addr> when NMU'ing;
+    update documentation accordingly
+    closes: #101676
+  * Matt Zimmerman fixes up some wording in the section talking about
+    forwarding bugs upstream
+    closes: #98312
+  * provide proper l10n for SGML date entities; now we have &date-<LANG>
+    entities which should be used
+  * debian/rules: fixes for new debiandoc-sgml
+  * debian/control: depend on debiandoc-sgml 1.1.48 or better
+
+ -- Adam Di Carlo <aph@debian.org>  Thu, 21 Jun 2001 14:43:42 -0400
+
+developers-reference (2.8.6) unstable; urgency=low
+
+  * fix a typo, thanks to Antoine Hulin
+  * French version: completely up-to-date now
+  * Makefile: add a 'validate' target
+  * prepare and ship "upstream" ChangeLog; move the debian changelog to
+    changelog.Debian.gz
+  * all versions: change the email address to use when orphaning
+    closes: #93727
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 13 Apr 2001 03:32:08 -0400
+
+developers-reference (2.8.5) unstable; urgency=low
+
+  * expunge references to the Debian Packaging Manual, which is now in the
+    Policy
+  * Japanese version: also comment out some references packaging manual;
+    this translation needs updating
+  * deny request to shut down non-maintainer bug maintenance bug closure
+    practices (closes: Bug#88623)
+  * add some advice about U.S. citizens uploading to non-US
+    (closes: Bug#89694)
+  * debian/control: Build-Depends should have been Build-Depends-Indep
+  * French version: First complete translation of the Debian developer's
+    reference guide.  Much work done by Antoine Hulin. Reviewed by Nicolas
+    Bertolissio.
+  * Portuguese version: work is started by Carlos Laviola, nothing
+    included yet, however
+
+ -- Adam Di Carlo <aph@debian.org>  Sun,  8 Apr 2001 01:25:51 -0400
+
+developers-reference (2.8.4) unstable; urgency=low
+
+  * debian/control: remove reference to obsolete packaging-manual package
+    (closes: Bug#86505)
+  * debian/control: fill in the description a bit more
+  * doc-base: index.html corrected to be index.en.html
+    (closes: Bug#85933)
+  * Makefile: clean is cleaner
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 25 Feb 2001 12:47:06 -0500
+
+developers-reference (2.8.3) unstable; urgency=low
+
+  * build and provide French and Japanese versions
+  * devolve build logic from debian/rules to top-level Makefile
+  * developers-reference.jp.sgml: minor changes so it will build (is out
+    of date)
+  * debian/rules: stop making useless /usr/share/developers-reference dir
+
+ -- Adam Di Carlo <aph@debian.org>  Mon, 22 Jan 2001 02:02:02 -0500
+
+developers-reference (2.8.2) unstable; urgency=low
+
+  * Josip Rodin:
+    - fix typographic errors reported by David Martinez (closes: Bug#80740)
+    - common.ent: upped the numbers a little bit, updated lintian reports URL
+    - updated regarding va->klecker move, and www->people move, changed
+      most mentions of dinstall to a generic term "archive maintenance
+      software", removed full path to it because it is in PATH now,
+      mentioned "dak" and "katie" (somewhat vaguely), changed week to
+      month regarding FTP archive waiting time since that\'s more often
+      the case, and changed weeks to hours regarding Maintainers file
+      updates since that\'s also more often the case now, updated some
+      URLs to entities, s/debian-doc/doc-debian/
+    - replaced evil latin1-only quotation marks, replaced mentions of
+      important severity (in RCB context) with serious severity, some
+      details fixed
+    - common.ent (1.10): fixed email-debian-user alias; updated
+      sample-dist-dirtree (with more to come)
+    - described testing; described package pools (this particular part
+      required quite a bit of changes, and it might be a bit rough, but
+      it's a start); described the frozen test cycles et al; some other
+      smaller fixes
+    - another update WRT sid/unstable/testing, from Colin Watson
+      (closes: Bug#80896)
+  * debian/control: add Recommends for debian-policy, packaging-manual 
+  * update copyright notice for 2001
+  * fix for WNPP bug filing severities from David Schleef
+  * clarify the status of the Developers's reference as "normative"
+  * add a reference to debconf (closes: Bug#82413)
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 21 Jan 2001 18:10:21 -0500
+
+developers-reference (2.8.1) unstable; urgency=low
+
+  * update WNPP instructions, based on patch from Marcelo E. Magallon 
+    (closes: Bug#69435)
+  * spelling corrections, awkward grammar suggestions from Andreas Krueger 
+    (closes: Bug#72810)
+  * debian/rules: remove some obsolete source-depends stuff
+
+ -- Adam Di Carlo <aph@debian.org>  Sat,  4 Nov 2000 13:22:21 -0500
+
+developers-reference (2.8.0) unstable; urgency=low
+
+  * Almost all changes for this release are from Josip Rodin
+    <joy@debian.org>. Thanks, Josip!
+
+  * debian/control, postinst, prerm, rules: Policy 3.2.1 (closes:
+    Bug#68929, Bug#70384)
+  * fixed bug closing example (closes: Bug#71198)
+  * update the perl regexp from current /usr/lib/dpkg/parsechangelog/debian
+  * updated keyring/keyserver information (closes: Bug#67783)
+  * updated new-maintainer stuff (closes: Bug#67841)
+  * updated for master -> ftp-master move (closes: Bug#68369)
+  * noted www.d.o is the right host for web pages, but all other machines
+    could be used if necessary
+  * reorder mentions of scp to come before FTP, as it is more secure;
+    mention the rsync dupload method
+  * reorder mentions of pandora <-> non-us, canonical name non-us is
+    better
+  * other small corrections
+  * fixed orphaning/adopting instructions with regard to the new WNPP
+  * common.ent: fix urls for cvs.d.o, wnpp, Debian machines page, 
+    lists-archives, www.d.o BTS
+  * common.ent: changed link for machines from devel/maintainer_contacts
+    to the db.d.o CGI
+  * Makefile: remove unnecessary subshell
+
+  * Adam's change: update debian/copyright for new Policy, and put my name
+    in there a bit with updated years; update doc-base file for FHS
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 15 Oct 2000 03:25:21 -0400
+
+developers-reference (2.7.2) frozen unstable; urgency=medium
+
+  * I believe this should go into frozen because (a) it's only
+    documentation, so it can't introduce RC bugs, and (b) it fixes an
+    error which prevented it from building properly; however, whatever
+    ftpmaster feels is best is fine
+  *
+  * include common.ent as well as version.ent 
+    (closes: Bug#52582, Bug#48926)
+  * debian/rules: fix build error caused by newer debiandoc-sgml; remove
+    constitution.en.html, since that is now located in the doc-debian
+    package (closes: Bug#54778, Bug#42014); don't compress .pdf file
+  *
+  * All changes below from Raphael Hertzog <hertzog@debian.org>
+  *
+  * Sec. "Uploading to master" and "Uploading to pandora": 
+    explained dinstall -n (closes: Bug#45079)
+  * Sec. "Picking a distribution": added reference to the debian-release
+    team (closes: Bug#52906)
+  * Sec. "Announcing package uploads": rewrote it to take care of the fact
+    that dinstall is doing it automatically (closes: Bug#43877)
+  * Sec. "Mailing lists": added a paragraph about debian-email
+    (closes: Bug#40258)
+  * Changed the "Maintaining Your Debian Information" into "Debian
+    Developer's Duties" (closes: Bug#28908)
+    - added a section about the LDAP database
+    - added a section about the "on vacation" message
+    - added a section about the coordination with upstream developers
+      (closes: Bug#43878)
+    - added a section about managing Release Critical bugs
+    - added a section about Quality Assurance effort
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 16 Apr 2000 23:24:33 -0400
+
+developers-reference (2.7.1) unstable; urgency=low
+
+  * Sec. "Registering as a Debian developer": we are transitioning away
+    from non-free PGP -- remove allusions to non-free software such as
+    PGPv2 or v5 insofar as possible; recommend use of DSS keys rather than
+    RSA
+  * Sec. "Maintaining Your Public Key": remove PGP-centric stuff
+  * Sec. "When bugs are closed by new uploads": describe how to close bugs
+    via a magic changelog entry (closes: Bug#43690)
+  * Sec. "Generating the changes file": refer to Sec. "When bugs are
+    closed by new uploads" for closing bugs via a changelog entry
+  * developers-reference.sgml: re-enable RCS variables in CVS sources
+  * debian/control,rules: dynamically generate the TOC in the package
+    description from developers-reference.sgml
+
+ -- Adam Di Carlo <aph@debian.org>  Sun, 12 Sep 1999 18:15:59 -0400
+
+developers-reference (2.7.0) unstable; urgency=low
+
+  * developers-reference.sgml: separated out language-independant elements
+    into common.ent (not content changes); misc minor grammar changes
+    throughout
+  * doc-base: change section for *constitution* to Debian (not 'debian')
+    (closes Bug#37392)
+  * Sec. "Stable, unstable, and sometimes frozen": mention how old stable
+    releases are available at archive.debian.org
+  * Sec. "Uploading to pandora (non-us)" added, remove stale
+    information about the old anonymous ftp area (closes Bug#39541);
+    Sec. "Other Upload Queues" added about that upload queues, added
+    samosa and master.debian.org.jp (closes Bug#37804)
+  * Sec. "Yada": mention that yada might not be as robust as other package
+    producing systems, at request of the author; Sec. "equivs" added
+  * Sec. "Moving packages": at the request of Guy Maor, clarify that this
+    procedure is for moving packages in sections (i.e., free, contrib)
+    only
+  * Sec. "Registering as a Debian developer": talk about RSA keys rather
+    than PGP keys, since I think GPG can create/handle them now; mention
+    that the official pkg maintainer address much match an ID on your key;
+  * Sec. "Maintaining Your Public Key": beef up the warnings a bit; point
+    to the PGP FAQ
+  * Sec. "Mailing Lists, Servers, and Other Machines": clean up and
+    clarify section; mention that all developers are expected to be
+    subscribed to debian-private and debian-devel-announce
+  * Sec. "Other Debian Machines": remove list of machines; point to
+    http://www.debian.org/devel/machines instead
+  * Sec. "Release code names": potato is 2.2
+  * Sec. "Guidelines for Porter Uploads": talk about recompile only
+    uploads and version numbers for this (i.e., foo_2.4-1.0.1), from a
+    suggestion from James Troup
+  * Sec. "buildd": mention andrea, and buildd.debian.org
+  * Sec. "Removing packages": correct apt-cache usage
+  * debain/rules: update standards to 3.0.1 -- since I'm not moving
+    /usr/doc to /usr/share/doc yet, no changes were required except in the
+    text here and there
+
+ -- Adam Di Carlo <aph@debian.org>  Mon, 16 Aug 1999 23:29:45 -0400
+
+developers-reference (2.6.8) unstable; urgency=low
+
+  * when applying as a new user, the login name can be *eight* characters,
+    not seven (thanks to Rafael Caetano dos Santos)
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 21 May 1999 21:50:04 -0400
+
+developers-reference (2.6.7) unstable; urgency=low
+
+  * SGML'ish: normalize SGML elements, refill paragraphs (closes Bug#37987)
+  * doc-base: change section to Debian -- hmm, this looks like a doc-base
+    bug, really, but hey, who am I to refile bugs to another one of my own
+    packages? (closes Bug#37392)
+  * Ch. "Overview of Debian Maintainer Tools": new section for yada (um,
+    someone who uses this should check my description), correct build ->
+    debuild in the devscripts section (closes Bug#38053)
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 21 May 1999 01:41:45 -0400
+
+developers-reference (2.6.6) unstable; urgency=low
+
+  * Sec. "The master server": note that problems on Debian ftp can be sent
+    to ftpmaster@debian.org also
+  * Secs. "Uploads via chiark" and "Uploads via erlangen": remove
+    'cron-driven' (thanks Roman Hodek)
+  * Sec. "Being Kind to Porters": typos corrected, note that binary-arch
+    and binary-indep targets should work independantly (thanks Roman
+    Hodek)
+  * Sec. "buildd": remove erroneous reference to debbuild, reorganize the
+    section and correct typos (thank again Roman -- boy, this is the all
+    Roman release)
+  * debian/rules: re-enable letter-sized PDFs
+
+ -- Adam Di Carlo <aph@debian.org>  Sun,  9 May 1999 01:17:29 -0400
+
+developers-reference (2.6.5) unstable; urgency=low
+
+  * Sec. "Architectures": correction on supported architecture in Linux
+    2.2, from Job Bogan
+  * Sec. "Experimental": other reasons to use or not use the experiment
+    archive "section", from comments by Guy Maor
+  * Sec. "Being Kind to Porters": replace x86 with i386 (closes Bug#36485)
+  * debian/rules: date printing protected from local l10n (closes Bug#36891)
+  * Ch. "Mailing Lists, Servers, and Other Machines": renamed chapter; add
+    intro paragraph
+  * Sec. "Debian Servers": new, for talking about the standard servers,
+    with intro; demoted server sections under that
+  * Sec. "The FTP servers": was empty, removed
+  * Sec. "The master server": fill in more info and cross-refs on how to
+    report problems
+  * Sec. "The CVS server": add some more detail which should be included
+    when requesting cvs areas; mention the cvsweb URL
+  * Sec. "Other Debian Machines": new section, list the machines for which
+    a normal developer may have access.
+
+ -- Adam Di Carlo <aph@debian.org>  Tue,  4 May 1999 03:32:21 -0400
+
+developers-reference (2.6.4) unstable; urgency=low
+
+  * debian/rules: hack 'byhand' file entries to include debian version
+    number in it, so subsequent uploads of the package into Incoming don't
+    step all over each other
+
+ -- Adam Di Carlo <aph@debian.org>  Fri,  9 Apr 1999 20:04:04 -0400
+
+developers-reference (2.6.3) unstable; urgency=low
+
+  * correction from James Troup -- <keyring-maint> is indeed the correct
+    address for PGP key updates
+
+ -- Adam Di Carlo <aph@debian.org>  Sun,  4 Apr 1999 13:28:58 -0400
+
+developers-reference (2.6.2) unstable; urgency=low
+
+  * Sec. "fakeroot": libtricks is not replacing anything after all
+  * developers-reference.sgml: use public declaration
+  * BTW, if any maintainers of translated versions of this document would
+    like to talk to me about folding your version into the
+    developers-reference CVS area, please get in touch with me
+
+ -- Adam Di Carlo <aph@debian.org>  Sun,  4 Apr 1999 04:42:29 -0400
+
+developers-reference (2.6.1) unstable; urgency=low
+
+  * include Debian constitution (closes Bug#30694)
+  * Sec. "fakeroot": libtricks is replacing fakeroot, not libtool
+  * Sec. "Maintaining Your Public Key" -- give email addresses as
+    {pgp,gpg}-update@debian.org, at James Troup's request (note to Jameas,
+    if you see this: /usr/doc/debian-keyring/README.gz talks about
+    <keyring-maint> instead)
+  * Ch. "Overview of Debian Maintainer Tools" -- add Sec. "debget"
+  * developers-reference.sgml: minor typo correction from Tril
+    <dem@tunes.org>
+  * doc-base stuff: add abstract to developers-reference, new file for
+    constitution
+  * debian/rules: minor cleanup and consistency; build PDF, not PS file;
+    ship PDF file;.text file now has .txt extension
+  * debian/control: set priority to optional, matching archive
+
+ -- Adam Di Carlo <aph@debian.org>  Sat,  3 Apr 1999 17:17:06 -0500
+
+developers-reference (2.6.0) frozen unstable; urgency=low
+
+  * would be nice to sneak this into slink; it's just documentation!
+  * Ch. "Porting and Being Ported": porter information broken out into it's
+    own chapter, Sec. "Guidelines for Porter Uploads" and "When to do a
+    source NMU if you are a porter" moved to this chapter; porter tool
+    descriptions such as 'quinn-diff' moved to this section.  Sec. "Being
+    Kind to Porters" added, with tips for how to avoid making problems for
+    porters.
+  * Ch. "Non-Maintainer Uploads (NMUs)": update for the new chapter, and
+    tighten up the language a bit
+  * Sec. "Monitoring bugs": add a little cron job to get an 'index maint'
+    of outstanding bugs (closes Bug#31259), loosen language a tiny bit
+    w.r.t. non-maintainers or submitters closing bugs (closes Bug#30394)
+  * Sec. "Scope of This Document": point out that this file is not
+    official policy
+  * Ch. "Handling Bugs": renamed from "Handling Bug Reports", incorporate
+    some suggestions from James Troup, namely, don't mail from your root
+    account, don't close bugs via control@bugs.debian.org; break out new
+    sections, "Submitting Bugs" and "Responding to Bugs"
+  * Ch. "Overview of Debian Maintainer Tools": remove attribution for
+    package maintainers, since I can't keep up; add entries for fakeroot
+    and devscripts
+  * Ch. "Maintaining Your Debian Information": new chapter, quite small
+    right now; it mentions keyring-maint@debian.org for key modification,
+    warns against putting private keys on multi-user machines, and talks
+    about how to depart Debian gracefully
+  * typo correction from Christian Hudon (closes Bug#32052)
+  * menu file removed, obsoleted by doc-base file
+  * parameterize some often-changing values with SGML entities, update
+    number of available packages
+  * use new way of notating multiple copyrights
+  * change <tt> elements to <file> where appropriate
+
+ -- Adam Di Carlo <aph@debian.org>  Thu, 11 Feb 1999 02:53:55 -0500
+
+developers-reference (2.5.0.5) unstable; urgency=low
+
+  * add version.ent to docdir, needed to reconstruct from SGML 
+    (closes Bug#31034)
+
+ -- Adam Di Carlo <aph@debian.org>  Tue, 29 Dec 1998 02:42:50 -0500
+
+developers-reference (2.5.0.4) unstable; urgency=low
+
+  * not officially released
+  * more spelling corrections
+  * s/ppc/powerpc/ (thanks, James Troup)
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 18 Dec 1998 00:07:40 -0500
+
+developers-reference (2.5.0.3) unstable; urgency=low
+
+  * not officially released
+  * Sec. "Removing a package from Incoming": tiny section added
+  * some PGP-centricity removed
+  * Sec. "Adopting a package": point out that hijacking packages is not ok 
+  * Ch. "Non-Maintainer Uploads (NMUs) and Porters": change 'NMU' to
+    'source NMU', 'port' to 'binary NMU', shorten the window for porters a
+    tad; fix spelling; stress that non-maintainer patches must be
+    non-disruptive and that aesthetic issues are not suitable for fixing
+    by non-maintainers; other fixes as suggested by interested parties
+
+ -- Adam Di Carlo <aph@debian.org>  Wed, 25 Nov 1998 00:01:27 -0500
+
+developers-reference (2.5.0.2) frozen unstable; urgency=low
+
+  * not officially released
+  * maintainer name change (but it's still me)
+  * Ch. "Non-Maintainer Uploads (NMUs) and Porters":  new chapter
+    discussing NMUs and porters; Section "Interim Releases" integrated out
+    of existance.  New TOC for this section is:
+         * 6 Non-Maintainer Uploads (NMUs) and Porters
+            + 6.1 Who can do a port or an NMU
+            + 6.2 When to do a port or an NMU
+                 o 6.2.1 When to do an NMU if you are a porter
+            + 6.3 How to do an NMU
+                 o 6.3.1 NMU version numbering
+                 o 6.3.2 NMUs must create a changelog entry
+                 o 6.3.3 NMUs must send patches, if any, to the BTS
+                 o 6.3.4 Building the NMU
+            + 6.4 Guidelines for Porters
+  
+  * Sec. "Maintainer changes": renamed to "Adopting a package" and moved
+    to Chapter "Moving, Removing, Renaming, Adopting, and Orphaning
+    Packages".
+  * Sec. "Reporting lots of bugs at once": more forcefully deprecate this
+    practice
+  * Sec. "Adopting a package": mention that the BTS maintainer update can
+    take a couple of weeks
+  * Sec. "Overview of Debian Maintainer Tools": give credit where credit
+    is due and attribute current maintainers; add `apt'; add `quinn-diff';
+    add mention of as yet unreleased 'buildd' package, since I'm so
+    excited about it and can't wait
+  * Sec. "Removing packages": talk about how apt-cache can be used to look
+    at reverse depends, a good step to take prior to removing a package
+    from the archive
+  * show *full* TOC, including sect2
+  * of course the obligatory typo, grammar, and spelling corrections
+
+  * Makefile: small changes to accomodate DDP autobuild
+  * debian/dirs: obsolete, removed
+  * debian/rules: use changelog date for SGML timestamping, not current date
+
+ -- Adam Di Carlo <aph@debian.org>  Fri, 20 Nov 1998 12:27:53 -0500
+
+developers-reference (2.5.0) frozen unstable; urgency=low
+
+  * move to 3-level version number:
+    top-level version number probably won't change for a while, it is the
+    "major", the second-level number means significant content changes,
+    and the third-level change means corrections and minor improvements.
+    Since this version has significant content changes, we are now 2.5.0.
+    Since I'm going to put porter instructions in the next major rev, that
+    will be 2.6.0...
+
+  * use new <package> tag where appropriate (Ardo, you rock)
+  * replace 'm86k' with 'm68k'
+  * rename 'Whirlwind Tour of ...' section to 'Overview of ...' (suggested 
+    by James Troup)
+  * typos and "red-pen" corrections, fix cosmetic problems in PostScript
+    version
+  * remove the one case I use an URL fragment identifier, since
+    debiandoc-sgml doesn't like it (bug filed against debiandoc-sgml)
+  * debian/rules: cosmetic cleanups, loosen check for root
+  * debian/rules: build PostScript version during build, since it's nice
+    to have all my debiandoc2* scripts together
+  * debian/control: policy compliant to 2.5.0
+
+  * advise against uploading when a package has lintian problems of
+    severity 'E'
+  * "Mailing Lists and Servers":
+    - "The master server": mention how master is the home of the BTS;
+      mention how users need to take care with their accounts on master
+    - "The WWW servers": fill in www.debian.org, first pass, and discuss
+      how to put up your own web pages on va or master
+    - "The CVS server": new section added
+    - "Mirrors of Debian servers": new section added; point to info about
+       how to mirror
+  * "Applying to Become a Maintainer": do not advise resending initial
+    application; instead, simply mail a followup asking new maintainers
+    whether they go the initial application (closes Bug #28739); mention
+    that calls usually come in the evening; mention that if you use PGP
+    v5, you need to generate an RSA key (right?); clarify our intentions
+    with respect to GPG.
+  * "Release code names": Debian 2.2 is 'potato'
+  * "Distribution directories": give concrete examples, hopefully making
+    it clearer where to look in Debian archives for specific stuff;
+    mention that old distributions are moved to archive servers (is there
+    a canonical location?)
+  * "The override file": new section, added under "Notification that a new
+    package has been installed"; fill it out quite a bit
+  * "Uploading to *": reiterate thrice not to upload export
+    controlled-software to master, or the European queues on erlangen and
+    chiark
+  * "Picking a distribution": section broken out from "Generating the
+    changes file"
+  * "Uploading to frozen": new section, almost straight from Brian White
+    (hope you don't mind!) -- isn't that topical?
+  * "Interim releases": if you NMU a new upstream version (0.1), run 
+    'dpkg-buildpackage -sa'
+
+ -- Adam P. Harris <aph@debian.org>  Thu, 12 Nov 1998 00:03:43 -0500
+
+developers-reference (2.4.1.5) unstable; urgency=low
+
+  * Fix instructions for new maintainers, incorporating the actual text
+    sent to prospective new maintainers.  Improve this text a bit for
+    readability, coverage, and organization.  Significant changes were
+    patched back to the new-maintainers group, if they care to use
+    them. (closes Bug#26948)
+  * Add an introductory "Scope" chapter which helps delineate what should
+    and should not be included in this Reference.
+  * Add a new chapter, "Whirlwind Tour of Debian Maintainer Tools".  Let
+    me know what useful tools I forgot -- remember, Debian-specific
+    maintainer tools only!
+  * Add discussion of the "experimental" distribution, culled from an email
+    from Guy Maor on debian-devel.
+  * Incorporated suggestions from Branden Robinson (closes Bug#27211).
+  * Point to doc-debian's mailing list instructions where relevant.
+  * Made references to online documentation into URLs where possible.
+  * Little corrections here and there.
+  * add a Makefile for use in the DDP manual hierarchy
+  * debian/rules: comment out my 'source-depends' hack; it's just slowing
+    things down
+
+ -- Adam P. Harris <aph@debian.org>  Thu,  1 Oct 1998 03:42:43 -0400
+
+developers-reference (2.4.1.4) unstable; urgency=low
+
+  * fill in Section "The master server" a bit; other servers to follow
+  * in Section "Distribution directories", mention that distributions
+    are always in 'dists' subdir of the Debian archive; talk about
+    'proposed-updates'
+  * in Section "Release code names", talk about 'sid' a bit
+  * in Section "Interim releases", talk about how non-maintainers should
+    use the BTS, and bug severity "fixed" (closes Bug#17524)
+  * in Section "Generating the changes file", talk about how to set the
+    distribution in the debian/changelog file (i.e., "frozen unstable")
+  * add a new Section "Checking the package prior to upload" to Section
+    "Uploading a package", mentioning lintian and other tests one should
+    do prior to uploading
+  * add new Section "Notification that a new package has been installed"
+    in Section "Uploading a package", talking about dinstall and the
+    override file a bit
+  * add new Sections "Moving packages", "Removing packages", "Replacing or
+    renaming packages", and "Orphaning a package" (closes Bug#26650)
+  * add new Section "Bugs in your packages", talking about maintainer
+    duties with respect to bugs
+  * add new Section "Lintian reports" under "Handling bugs reports",
+    talking about how maintainers should check their packages with lintian 
+    every now and then, alternatively pointing them to the lintian web
+    pages
+  * clarify, a bit, the use of "section" and "subsection", bringing it
+    into line with the usage in the Policy Manual and Packaging Manual
+  * grammar and markup changes throughout
+  * debian/rules: added a crude source-depends rule, which renders more
+    explicit what is used to build this package
+
+ -- Adam P. Harris <aph@debian.org>  Mon, 21 Sep 1998 00:51:46 -0400
+
+developers-reference (2.4.1.3) unstable; urgency=low
+
+  * new maintainer
+  * version number and date are automatically populated now
+  * changed doc-base section to "debian"
+  * debian/rules: better abstraction and organization
+  * reformat SGML like I happen to like it
+  * utilize the new URL tag
+  * build PostScript on letter size, I hear thats better for A4 and US
+    letter printing
+
+ -- Adam P. Harris <aph@debian.org>  Thu, 16 Jul 1998 00:52:35 -0400
+
+developers-reference (2.4.1.2) frozen unstable; urgency=low
+
+  * non-maintainer release
+  * rebuilt since HTML versions of Chapters 1 and 2 were truncated
+    (important bug, no number yet, bugs.debian.org isn't working;
+    regardless, this should go in hamm because a broken developers
+    reference won't win us many friends in hamm, and after all, it's just
+    text, it can't hurt you.)
+  * no content changes, except that the version number in the SGML file
+    reflect this packages version number
+  * debian/rule: clean is cleaner now
+
+ -- Adam P. Harris <aph@debian.org>  Tue, 16 Jun 1998 01:35:39 -0400
+
+developers-reference (2.4.1.1) frozen unstable; urgency=low
+
+  * Orphaned package
+
+ -- Christian Schwarz <schwarz@debian.org>  Thu, 14 May 1998 21:56:36 +0200
+
+developers-reference (2.4.1.0) frozen unstable; urgency=low
+
+  * New version numbering scheme:
+  
+    - The version numbers are independent of dpkg now, but all policy
+      manuals (the Debian Policy Manual, the Debian Packaging Manual, and
+      the Debian Developer's Reference) share the same version numbering
+      scheme.
+    
+    - The first three digits of the version number specify the
+      `Standards-Version.' This number is incremented with each policy
+      change. The fourth digit represents the `patch-level,' which may
+      differ between the manuals. 
+  
+      If only the patch-level digit is incremented, no changes in policy
+      have been made, except bug fixes and clarifications. Packages only
+      have to specify the first three digits of the version number in the
+      `Standards-Version' field of their source packages.
+  
+  * Uploaded to frozen and unstable. This is a documentation-only
+    package and the changes to the manual are relevant for hamm.
+
+  * No changes to the Developer's Reference
+  
+ -- Christian Schwarz <schwarz@debian.org>  Mon, 13 Apr 1998 17:54:43 +0200
+
+developers-reference (0.5) unstable; urgency=low
+
+  * Changes to the Developer's Reference:
+  
+    - Changed section 1.2 Registering as a Debian developer:
+      + signatures from formal certification service are _NOT_ accepted
+        anymore
+      + images of ID documents have to be PGP or RSA signed
+      (as requested by James Troup)
+  
+    - Use current date instead of <date> in manual
+    
+  * Updated FSF's address (reported by Lintian)
+
+ -- Christian Schwarz <schwarz@debian.org>  Sat,  7 Mar 1998 13:52:15 +0100
+
+developers-reference (0.4) unstable; urgency=low
+
+  * Changes to the Developer's Reference:
+
+    - Renamed chapter 4 into `Package uploads'
+
+    - New section 4.2.5 Uploading to the non-us server
+
+    - Changed section 4.4 Interim releases:
+      + non-maintainer releases should not close bugs
+      + normal maintainer must at least read the patch provided with
+        the non-maintainer release
+
+    - New chapter 5 Handling bug reports:
+      + when reporting more then 10 bugs on the same topic, a message
+        has to be sent to debian-devel and the `maintonly' address
+        should be used
+
+    - Lots of typos fixed
+
+  * Compressed SGML source code
+
+  * Added support for doc-base to register the Developer's Reference
+    to the online documentation systems dwww and dhelp
+
+  * Upgraded to standards version 2.4.0.0 (no changes)
+  
+ -- Christian Schwarz <schwarz@debian.org>  Fri, 30 Jan 1998 21:58:34 +0100
+  
+developers-reference (0.3) unstable; urgency=low
+
+  * Put lost sections from Policy Manual 2.1.3.3 back in:
+      - Generating the changes file (for uploads)
+      - Announcing package uploads
+  * New section about Debian Mentors
+  * debian/rules: Don't use debstd anymore
+  * debian/rules: Compress changelog file (fixes:#15441)
+  * Fixed link to WNPP list (fixes:#16201)
+  * Added menu entry (fixes:#15708)
+  
+ -- Christian Schwarz <schwarz@debian.org>  Wed, 24 Dec 1997 13:54:33 +0100
+  
+developers-reference (0.2) unstable; urgency=low
+
+  * New chapter about `The Debian Archive' describing the structure
+    of our FTP server and the development process
+  * Added note that new maintainers have to read the Social Contract
+    and have to know where to find the Policy and Packaging Manuals
+  * PGP key ring is not distributed via dpkg but in doc/ of the FTP
+    server
+  * Added note that cross posting between Debian lists is depreciated
+  * New list of advantages why new packages should be discussed on
+    debian-devel before they are uploaded
+  * Added section about how packages are uploaded
+  * Added note that the Security Managers may do interim releases without 
+    contacting the maintainer
+  * Removed chapter about bug tracking system (will be included in
+    a new manual released soon)
+  * Some minor changes
+  * Include SGML source in package
+  * Don't use `2-up' style for PostScript version
+  * Upgraded to Standards 2.3.0.1
+
+ -- Christian Schwarz <schwarz@debian.org>  Sun,  2 Nov 1997 20:53:26 +0100
+  
+developers-reference (0.1) unstable; urgency=low
+
+  * Initial Release.
+
+ -- Christian Schwarz <schwarz@debian.org>  Tue, 8 Jul 1997 00:19:49 +0200
+
diff --git a/debian/compat b/debian/compat
new file mode 100644 (file)
index 0000000..b8626c4
--- /dev/null
@@ -0,0 +1 @@
+4
diff --git a/debian/control b/debian/control
new file mode 100644 (file)
index 0000000..bf8e7c1
--- /dev/null
@@ -0,0 +1,41 @@
+Source: developers-reference
+Section: doc
+Priority: optional
+Maintainer: Debian Documentation Project <debian-doc@lists.debian.org>
+Uploaders: Andreas Barth <aba@not.so.argh.org>
+Standards-Version: 3.7.2
+Build-Depends-Indep: docbook-xsl (>= 1.71.0), dblatex (>= 0.2)
+Build-Depends: debhelper (>= 4.1.32)
+
+Package: developers-reference
+Architecture: all
+Recommends: debian-policy
+Suggests: doc-base
+Description: guidelines and information for Debian developers
+ This package contains the Debian Developer's Reference, a set of
+ guidelines and best practices which has been established by and for
+ the community of Debian developers.  If you are not a Debian
+ developer, you probably do not need this package.
+ .
+ Table of Contents:
+ .
+ ${TOC:en}
+ .
+ This package contains the English version of the Developer's
+ Reference.  The French translation is available in
+ developers-reference-fr.
+
+Package: developers-reference-fr
+Architecture: all
+Recommends: debian-policy
+Suggests: doc-base
+Description: guidelines and information for Debian developers, in French
+ This package contains the French translation of Debian Developer's
+ Reference (package: developers-reference), a set of guidelines and
+ best practices which has been established by and for the community of
+ Debian developers.  If you are not a Debian developer, you probably
+ do not need this package.
+ .
+ Table of Contents (in English):
+ .
+ ${TOC:en}
diff --git a/debian/copyright b/debian/copyright
new file mode 100644 (file)
index 0000000..039af5a
--- /dev/null
@@ -0,0 +1,29 @@
+
+This is the Debian package of the Debian Developer's Reference.  It
+was assembled by Christian Schwarz <schwarz@debian.org>, has been maintained
+by Adam Di Carlo <aph@debian.org> and is now maintained by Andreas Barth
+<aba@not.so.argh.org>.
+
+------------------------------------------------------------------------------
+Copyright of the Debian Developer's Reference:
+
+Copyright (c) 1997, 1998 Christian Schwarz; 
+          (c) 2002 - 2003 Raphaël Hertzog
+          (c) 1998 - 2003 Adam Di Carlo
+          (c) 2004 - 2007 Andreas Barth
+
+This manual is free software; you may redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 2, or (at your option) any
+later version.
+
+This is distributed in the hope that it will be useful, but without
+any warranty; without even the implied warranty of merchantability or
+fitness for a particular purpose. See the GNU General Public License
+for more details.
+
+A copy of the GNU General Public License is available as
+`/usr/share/common-licenses/GPL' in the Debian GNU/Linux distribution
+or on the World Wide Web at <URL:http://www.gnu.org/copyleft/gpl.html>.
+You can also obtain it by writing to the Free Software Foundation, Inc., 
+51 Franklin St, Fifth Floor, Boston, MA 02110, USA
diff --git a/debian/developers-reference-fr.doc-base b/debian/developers-reference-fr.doc-base
new file mode 100644 (file)
index 0000000..40ed300
--- /dev/null
@@ -0,0 +1,17 @@
+Document: developers-reference-fr
+Title: Debian Developer's Reference, French translation
+Author: Adam Di Carlo, Josip Rodin, Raphaël Hertzog, et al
+Abstract: Overview of available resources, standard package
+  maintenance procedures, duties and best practices for Debian
+  developers.  This document describes, for instance, how to orphan a
+  package, how to maintain your public key, how to rename a package,
+  how to do an NMU, guidelines for porters, available packaging tools,
+  and the like.
+Section: Debian
+
+Format: HTML
+Index: /usr/share/doc/developers-reference-fr/index.fr.html
+Files: /usr/share/doc/developers-reference-fr/*.html
+
+Format: PDF
+Files: /usr/share/doc/developers-reference-fr/developers-reference.fr.pdf
diff --git a/debian/developers-reference-ja.doc-base b/debian/developers-reference-ja.doc-base
new file mode 100644 (file)
index 0000000..6da6b18
--- /dev/null
@@ -0,0 +1,14 @@
+Document: developers-reference-ja
+Title: Debian Developer's Reference, Japanese translation
+Author: Adam Di Carlo, Josip Rodin, Raphaël Hertzog, et al
+Abstract: Overview of available resources, standard package
+  maintenance procedures, duties and best practices for Debian
+  developers.  This document describes, for instance, how to orphan a
+  package, how to maintain your public key, how to rename a package,
+  how to do an NMU, guidelines for porters, available packaging tools,
+  and the like.
+Section: Debian
+
+Format: HTML
+Index: /usr/share/doc/developers-reference-ja/index.ja.html
+Files: /usr/share/doc/developers-reference-ja/*.html
diff --git a/debian/developers-reference.doc-base b/debian/developers-reference.doc-base
new file mode 100644 (file)
index 0000000..362024a
--- /dev/null
@@ -0,0 +1,20 @@
+Document: developers-reference
+Title: Debian Developer's Reference
+Author: Adam Di Carlo, Josip Rodin, Raphaël Hertzog, et al
+Abstract: Overview of available resources, standard package
+  maintenance procedures, duties and best practices for Debian
+  developers.  This document describes, for instance, how to orphan a
+  package, how to maintain your public key, how to rename a package,
+  how to do an NMU, guidelines for porters, available packaging tools,
+  and the like.
+Section: Debian
+
+Format: text
+Files: /usr/share/doc/developers-reference/developers-reference.txt.gz
+
+Format: HTML
+Index: /usr/share/doc/developers-reference/index.en.html
+Files: /usr/share/doc/developers-reference/*.html
+
+Format: PDF
+Files: /usr/share/doc/developers-reference/developers-reference.pdf
diff --git a/debian/rules b/debian/rules
new file mode 100755 (executable)
index 0000000..4311407
--- /dev/null
@@ -0,0 +1,106 @@
+#!/usr/bin/make -f
+# rules file for developers-reference
+
+package                := developers-reference
+
+# directory abstraction
+prefix         := debian/$(package)
+docdir         := $(prefix)/usr/share/doc/$(package)
+docbaserel     := /usr/share/doc-base
+docbasedir     := $(prefix)$(docbaserel)
+
+# list of language packages, in the form pkg-LANG; must jibe
+# with debian/control, see also DATE_uc(LANG) below
+langs          := fr
+
+# tool abstraction
+install_file   := install -o root -g root -m 644 -p
+install_script := install -o root -g root -m 755 -p
+make_directory := install -d -o root -g root -m 755
+
+# version abstraction
+DEB_VERSION    := $(shell awk -F '[()]' '/^$(package)/{ print $$2; exit }' debian/changelog)
+DEB_DATE       := $(shell dpkg-parsechangelog 2>/dev/null | sed -n 's/^Date: *//p')
+# pretty-print the date; I wish this was dynamic like the top-level makefile but oh well
+DATE_EN                := $(shell LC_ALL=C     date --date="$(DEB_DATE)" '+%d %B, %Y')
+DATE_FR                := $(shell LC_ALL=fr_FR date --date="$(DEB_DATE)" '+%d %B %Y')
+DATE_JA                := $(shell LC_ALL=ja_JP date --date="$(DEB_DATE)" '+%x')
+
+# debhelper verbose mode
+#export DH_VERBOSE=1
+
+version.ent:   debian/changelog
+       :> version.ent
+       echo "<!ENTITY version \"$(DEB_VERSION)\">" >> version.ent
+       echo "<!ENTITY date-en \"$(DATE_EN)\">"     >> version.ent
+       echo "<!ENTITY date-fr \"$(DATE_FR)\">"     >> version.ent
+       echo "<!ENTITY date-ja \"$(DATE_JA)\">"     >> version.ent
+
+build:
+       $(checkdir)
+       $(MAKE)
+       touch build
+
+.PHONY: clean
+clean:
+       $(checkdir)
+       $(MAKE) clean
+       rm -f build
+       dh_clean
+
+.PHONY: test
+test:
+#       nothing to test ATM
+
+.PHONY: install
+install:       build
+       $(checkdir)
+       $(checkroot)
+       dh_clean -k
+
+       dh_installdocs -p$(package) README-contrib developers-reference.txt \
+               developers-reference.pdf developers-reference.html/*
+
+       set -e; for lang in $(langs); do \
+           dh_installdocs -p$(package)-$$lang README-contrib developers-reference.$$lang.txt \
+               developers-reference.$$lang.pdf developers-reference.$$lang.html/* ;\
+       done
+
+
+.PHONY: binary-indep
+binary-indep:  test install
+       $(checkdir)
+       $(checkroot)
+       dh_installdirs -i
+       dh_installchangelogs -i
+       dh_compress -i -X.pdf
+       dh_fixperms -i
+       debian/tocsubstvars -i
+       dh_installdeb -i
+       dh_gencontrol -i
+       dh_md5sums -i
+       dh_builddeb -i
+
+
+.PHONY: binary-arch
+binary-arch:   build install
+#       There are no architecture-dependent files to be uploaded
+#       generated by this package.
+
+define checkdir
+       test -f debian/rules
+       test -f developers-reference.sgml
+endef
+
+# Below here is fairly generic really
+
+define checkroot
+       test `id -u` = 0
+endef
+
+.PHONY: binary
+binary:                binary-indep binary-arch
+
+#Local variables:
+#mode: makefile
+#End:
diff --git a/debian/tocsubstvars b/debian/tocsubstvars
new file mode 100755 (executable)
index 0000000..ac7fed6
--- /dev/null
@@ -0,0 +1,37 @@
+#!/usr/bin/perl -w
+
+use strict;
+use Debian::Debhelper::Dh_Lib;
+
+init();
+
+sub gettoc {
+    my $f = shift;
+    my @toc;
+
+    open(FILE, "<$f") || die("opening $f: $!\n");
+    while (<FILE>) {
+        chomp;
+        /^\d+\.\s/ && push(@toc, $_);
+    }
+    close(FILE) || die("closing $f: $!\n");
+    return @toc;
+}
+
+my @entoc = gettoc("developers-reference.txt");
+
+# sanity test
+if ( $#entoc == -1 ) {
+    error("found no entries in the TOC, aborting");
+} elsif ( $#entoc < 4 ) {
+    error("only found " . $#entoc . " entries in the TOC, aborting");
+}
+verbose_print("found " . $#entoc . " entries in TOC");
+
+my $entoc = "   " . join('${Newline}    ', @entoc);
+
+foreach my $package (@{$dh{DOPACKAGES}}) {
+    addsubstvar($package, "TOC:en", $entoc);
+}
+
+
diff --git a/developer-duties.dbk b/developer-duties.dbk
new file mode 100644 (file)
index 0000000..899b567
--- /dev/null
@@ -0,0 +1,212 @@
+<?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">
+<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
+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
+choose to subscribe there.
+</para>
+<para>
+For more information about the database, please see <xref linkend="devel-db"/>
+.
+</para>
+</section>
+
+<section id="key-maint">
+<title>Maintaining your public key</title>
+<para>
+Be very careful with your private keys.  Do not place them on any public
+servers or multiuser machines, such as the Debian servers (see <xref
+linkend="server-machines"/> ).  Back your keys up; keep a copy offline.  Read
+the documentation that comes with your software; read the <ulink
+url="http://www.cam.ac.uk.pgp.net/pgpnet/pgp-faq/">PGP FAQ</ulink>.
+</para>
+<para>
+You need to ensure not only that your key is secure against being stolen, but
+also that it is secure against being lost.  Generate and make a copy (best also
+in paper form) of your revocation certificate; this is needed if your key is
+lost.
+</para>
+<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>.
+</para>
+<para>
+If you need to add a completely new key or remove an old key, you need to get
+the new key signed by another developer.  If the old key is compromised or
+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>.
+</para>
+<para>
+The same key extraction routines discussed in <xref linkend="registering"/>
+apply.
+</para>
+<para>
+You can find a more in-depth discussion of Debian key maintenance in the
+documentation of the <systemitem role="package">debian-keyring</systemitem>
+package.
+</para>
+</section>
+
+<section id="voting">
+<title>Voting</title>
+<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
+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
+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
+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
+with information on how to make, second and vote on proposals.
+</para>
+</section>
+
+<section id="inform-vacation">
+<title>Going on vacation gracefully</title>
+<para>
+It is common for developers to have periods of absence, whether those are
+planned vacations or simply being buried in other work.  The important thing to
+notice is that other developers need to know that you're on vacation so that
+they can do whatever is needed if a problem occurs with your packages or other
+duties in the project.
+</para>
+<para>
+Usually this means that other developers are allowed to NMU (see <xref
+linkend="nmu"/> ) your package if a big problem (release critical bug, security
+update, etc.) occurs while you're on vacation.  Sometimes it's nothing as
+critical as that, but it's still appropriate to let others know that you're
+unavailable.
+</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
+[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
+vacation.  You can also give some special instructions on what to do if a
+problem occurs.
+</para>
+<para>
+The other thing to do is to mark yourself as on vacation in the
+<link linkend="devel-db">Debian developers' LDAP database</link> (this
+information is only accessible to Debian developers).  Don't forget to remove
+the on vacation flag when you come back!
+</para>
+<para>
+Ideally, you should sign up at the <ulink
+url="http://nm.debian.org/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.
+</para>
+</section>
+
+<section id="upstream-coordination">
+<title>Coordination with upstream developers</title>
+<para>
+A big part of your job as Debian maintainer will be to stay in contact with the
+upstream developers.  Debian users will sometimes report bugs that are not
+specific to Debian to our bug tracking system.  You have to forward these bug
+reports to the upstream developers so that they can be fixed in a future
+upstream release.
+</para>
+<para>
+While it's not your job to fix non-Debian specific bugs, you may freely do so
+if you're able.  When you make such fixes, be sure to pass them on to the
+upstream maintainers as well.  Debian users and developers will sometimes
+submit patches to fix upstream bugs — you should evaluate and forward these
+patches upstream.
+</para>
+<para>
+If you need to modify the upstream sources in order to build a policy compliant
+package, then you should propose a nice fix to the upstream developers which
+can be included there, so that you won't have to modify the sources of the next
+upstream version.  Whatever changes you need, always try not to fork from the
+upstream sources.
+</para>
+</section>
+
+<section id="rc-bugs">
+<title>Managing release-critical bugs</title>
+<para>
+Generally you should deal with bug reports on your packages as described in
+<xref linkend="bug-handling"/> .  However, there's a special category of bugs
+that you need to take care of — the so-called release-critical bugs (RC
+bugs).  All bug reports that have severity <emphasis>critical</emphasis>,
+<emphasis>grave</emphasis> or <emphasis>serious</emphasis> are considered to
+have an impact on whether the package can be released in the next stable
+release of Debian.  These bugs can delay the Debian release and/or can justify
+the removal of a package at freeze time.  That's why these bugs need to be
+corrected as quickly as possible.
+</para>
+<para>
+Developers who are part of the <ulink url="http://qa.debian.org/">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
+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
+usual before they do their NMU if they have seen no recent activity from you in
+the BTS).
+</para>
+</section>
+
+<section id="s3.7">
+<title>Retiring</title>
+<para>
+If you choose to leave the Debian project, you should make sure you do the
+following steps:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Orphan all your packages, as described in <xref linkend="orphaning"/> .
+</para>
+</listitem>
+<listitem>
+<para>
+Send an gpg-signed email about why you are leaving the project to
+<email>debian-private@lists.debian.org</email>.
+</para>
+</listitem>
+<listitem>
+<para>
+Notify the Debian key ring maintainers that you are leaving by opening a ticket
+in Debian RT by sending a mail to keyring@rt.debian.org with the words 'Debian
+RT' somewhere in the subject line (case doesn't matter).
+</para>
+</listitem>
+</orderedlist>
+</section>
+
+</chapter>
+
diff --git a/index.dbk b/index.dbk
new file mode 100644 (file)
index 0000000..07036fc
--- /dev/null
+++ b/index.dbk
@@ -0,0 +1,101 @@
+<?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">
+<book lang="en">
+
+<title>Debian Developer's Reference</title>
+<bookinfo>
+<author>
+<othername>Developer's Reference Team</othername>
+<email>developers-reference@packages.debian.org</email> 
+</author>
+<author>
+<firstname>Andreas</firstname> <surname>Barth</surname>
+</author>
+<author>
+<firstname>Adam</firstname> <surname>Di Carlo</surname>
+</author>
+<author>
+<firstname>Raphaël</firstname> <surname>Hertzog</surname>
+</author>
+<author>
+<firstname>Christian</firstname> <surname>Schwarz</surname>
+</author>
+<author>
+<firstname>Ian</firstname> <surname>Jackson</surname>
+</author>
+<releaseinfo>ver. 3.3.9, 16 June, 2007</releaseinfo>
+<pubdate><!-- put date --></pubdate>
+<copyright>
+<year>2004</year>
+<year>2005</year>
+<year>2006</year>
+<year>2007</year>
+<holder>Andreas Barth</holder>
+</copyright>
+<copyright>
+<year>1998</year>
+<year>1999</year>
+<year>2000</year>
+<year>2001</year>
+<year>2002</year>
+<year>2003</year>
+<holder>Adam Di Carlo</holder>
+</copyright>
+<copyright>
+<year>2002</year>
+<year>2003</year>
+<holder>Raphaël Hertzog</holder>
+</copyright>
+<copyright>
+<year>1997</year>
+<year>1998</year>
+<holder>Christian Schwarz</holder>
+</copyright>
+<legalnotice>
+<para>
+This manual is free software; you may redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2, or (at your option) any later version.
+</para>
+<para>
+This is distributed in the hope that it will be useful, but <emphasis>without
+any warranty</emphasis>; without even the implied warranty of merchantability
+or fitness for a particular purpose.  See the GNU General Public License for
+more details.
+</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
+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.
+</para>
+<para>
+If you want to print this reference, you should use the <ulink
+url="developers-reference.pdf">pdf version</ulink>.  This page is also
+available in <ulink url="index.fr.html">French</ulink>.
+</para>
+</legalnotice>
+<!-- toc -->
+</bookinfo>
+<xi:include href="scope.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="new-maintainer.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="developer-duties.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="resources.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="pkgs.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="best-pkging-practices.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="beyond-pkging.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="l10n.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="tools.dbk"
+xmlns:xi="http://www.w3.org/2003/XInclude"/>
+</book>
diff --git a/l10n.dbk b/l10n.dbk
new file mode 100644 (file)
index 0000000..76203f3
--- /dev/null
+++ b/l10n.dbk
@@ -0,0 +1,238 @@
+<?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">
+<chapter id="l10n">
+<title>Internationalizing, translating, being internationalized and being translated</title>
+<para>
+Debian supports an ever-increasing number of natural languages.  Even if you
+are a native English speaker and do not speak any other language, it is part of
+your duty as a maintainer to be aware of issues of internationalization
+(abbreviated i18n because there are 18 letters between the 'i' and the 'n' in
+internationalization).  Therefore, even if you are ok with English-only
+programs, you should read most of this chapter.
+</para>
+<para>
+According to <ulink
+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
+L10N (localization) means implementation of a specific language for an already
+internationalized software.
+</para>
+<para>
+l10n and i18n are interconnected, but the difficulties related to each of them
+are very different.  It's not really difficult to allow a program to change the
+language in which texts are displayed based on user settings, but it is very
+time consuming to actually translate these messages.  On the other hand,
+setting the character encoding is trivial, but adapting the code to use several
+character encodings is a really hard problem.
+</para>
+<para>
+Setting aside the i18n problems, where no general guideline can be given, there
+is actually no central infrastructure for l10n within Debian which could be
+compared to the dbuild mechanism for porting.  So most of the work has to be
+done manually.
+</para>
+<section id="l10n-handling">
+<title>How translations are handled within Debian</title>
+<para>
+Handling translation of the texts contained in a package is still a manual
+task, and the process depends on the kind of text you want to see translated.
+</para>
+<para>
+For program messages, the gettext infrastructure is used most of the time.
+Most of the time, the translation is handled upstream within projects like the
+<ulink url="http://www.iro.umontreal.ca/contrib/po/HTML/">Free Translation
+Project</ulink>, the <ulink
+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
+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.
+</para>
+<para>
+An effort to translate the package descriptions started long ago, even if very
+little support is offered by the tools to actually use them (i.e., only APT can
+use them, when configured correctly).  Maintainers don't need to do anything
+special to support translated package descriptions; translators should use the
+<ulink url="http://ddtp.debian.org/">DDTP</ulink>.
+</para>
+<para>
+For debconf templates, maintainers should use the po-debconf package to ease
+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
+statistics</ulink> site (about what is integrated in the packages).
+</para>
+<para>
+For web pages, each l10n team has access to the relevant CVS, and the
+statistics are available from the Central Debian translation statistics site.
+</para>
+<para>
+For general documentation about Debian, the process is more or less the same as
+for the web pages (the translators have access to the CVS), but there are no
+statistics pages.
+</para>
+<para>
+For package-specific documentation (man pages, info documents, other formats),
+almost everything remains to be done.
+</para>
+<para>
+Most notably, the KDE project handles translation of its documentation in the
+same way as its program messages.
+</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
+repository</ulink>.
+</para>
+</section>
+
+<section id="l10n-faqm">
+<title>I18N &amp; L10N FAQ for maintainers</title>
+<para>
+This is a list of problems that maintainers may face concerning i18n and l10n.
+While reading this, keep in mind that there is no real consensus on these
+points within Debian, and that this is only advice.  If you have a better idea
+for a given problem, or if you disagree on some points, feel free to provide
+your feedback, so that this document can be enhanced.
+</para>
+<section id="l10n-faqm-tr">
+<title>How to get a given text translated</title>
+<para>
+To translate package descriptions or debconf templates, you have nothing to do;
+the DDTP infrastructure will dispatch the material to translate to volunteers
+with no need for interaction from your part.
+</para>
+<para>
+For all other material (gettext files, man pages, or other documentation), the
+best solution is to put your text somewhere on the Internet, and ask on
+debian-i18n for a translation in different languages.  Some translation team
+members are subscribed to this list, and they will take care of the translation
+and of the reviewing process.  Once they are done, you will get your translated
+document from them in your mailbox.
+</para>
+</section>
+
+<section id="l10n-faqm-rev">
+<title>How to get a given translation reviewed</title>
+<para>
+From time to time, individuals translate some texts in your package and will
+ask you for inclusion of the translation in the package.  This can become
+problematic if you are not fluent in the given language.  It is a good idea to
+send the document to the corresponding l10n mailing list, asking for a review.
+Once it has been done, you should feel more confident in the quality of the
+translation, and feel safe to include it in your package.
+</para>
+</section>
+
+<section id="l10n-faqm-update">
+<title>How to get a given translation updated</title>
+<para>
+If you have some translations of a given text lying around, each time you
+update the original, you should ask the previous translator to update the
+translation with your new changes.  Keep in mind that this task takes time; at
+least one week to get the update reviewed and all.
+</para>
+<para>
+If the translator is unresponsive, you may ask for help on the corresponding
+l10n mailing list.  If everything fails, don't forget to put a warning in the
+translated document, stating that the translation is somehow outdated, and that
+the reader should refer to the original document if possible.
+</para>
+<para>
+Avoid removing a translation completely because it is outdated.  Old
+documentation is often better than no documentation at all for non-English
+speakers.
+</para>
+</section>
+
+<section id="l10n-faqm-bug">
+<title>How to handle a bug report concerning a translation</title>
+<para>
+The best solution may be to mark the bug as forwarded to upstream, and forward
+it to both the previous translator and his/her team (using the corresponding
+debian-l10n-XXX mailing list).
+</para>
+</section>
+
+</section>
+
+<section id="l10n-faqtr">
+<title>I18N &amp; L10N FAQ for translators</title>
+<para>
+While reading this, please keep in mind that there is no general procedure
+within Debian concerning these points, and that in any case, you should
+collaborate with your team and the package maintainer.
+</para>
+<section id="l10n-faqtr-help">
+<title>How to help the translation effort</title>
+<para>
+Choose what you want to translate, make sure that nobody is already working on
+it (using your debian-l10n-XXX mailing list), translate it, get it reviewed by
+other native speakers on your l10n mailing list, and provide it to the
+maintainer of the package (see next point).
+</para>
+</section>
+
+<section id="l10n-faqtr-inc">
+<title>How to provide a translation for inclusion in a package</title>
+<para>
+Make sure your translation is correct (asking for review on your l10n mailing
+list) before providing it for inclusion.  It will save time for everyone, and
+avoid the chaos resulting in having several versions of the same document in
+bug reports.
+</para>
+<para>
+The best solution is to file a regular bug containing the translation against
+the package.  Make sure to use the 'PATCH' tag, and to not use a severity
+higher than 'wishlist', since the lack of translation never prevented a program
+from running.
+</para>
+</section>
+
+</section>
+
+<section id="l10n-best">
+<title>Best current practice concerning l10n</title>
+<itemizedlist>
+<listitem>
+<para>
+As a maintainer, never edit the translations in any way (even to reformat the
+layout) without asking on the corresponding l10n mailing list.  You risk for
+example breaksing the encoding of the file by doing so.  Moreover, what you
+consider an error can be right (or even needed) in the given language.
+</para>
+</listitem>
+<listitem>
+<para>
+As a translator, if you find an error in the original text, make sure to report
+it.  Translators are often the most attentive readers of a given text, and if
+they don't report the errors they find, nobody will.
+</para>
+</listitem>
+<listitem>
+<para>
+In any case, remember that the major issue with l10n is that it requires
+several people to cooperate, and that it is very easy to start a flamewar about
+small problems because of misunderstandings.  So if you have problems with your
+interlocutor, ask for help on the corresponding l10n mailing list, on
+debian-i18n, or even on debian-devel (but beware, l10n discussions very often
+become flamewars on that list :)
+</para>
+</listitem>
+<listitem>
+<para>
+In any case, cooperation can only be achieved with <emphasis
+role="strong">mutual respect</emphasis>.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+</chapter>
+
diff --git a/new-maintainer.dbk b/new-maintainer.dbk
new file mode 100644 (file)
index 0000000..e277466
--- /dev/null
@@ -0,0 +1,217 @@
+<?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">
+<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'
+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
+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>.
+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
+mandatory for anyone who wishes to follow Debian's development.
+</para>
+<para>
+You should subscribe and lurk (that is, read without posting) for a bit before
+doing any coding, and you should post about your intentions to work on
+something to avoid duplicated effort.
+</para>
+<para>
+Another good list to subscribe to is
+<email>debian-mentors@lists.debian.org</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
+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
+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
+more information on sponsoring).  On the other hand, if you are interested in
+porting Debian to alternative architectures or kernels you can subscribe to
+port specific mailing lists and ask there how to get started.  Finally, if you
+are interested in documentation or Quality Assurance (QA) work you can join
+maintainers already working on these tasks and submit patches and improvements.
+</para>
+<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.
+</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
+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).
+</para>
+<para>
+Those who prefer one-on-one help (e.g., via private email) should also post to
+that list and an experienced developer will volunteer to help.
+</para>
+<para>
+In addition, if you have some packages ready for inclusion in Debian, but are
+waiting for your new maintainer application to go through, you might be able
+find a sponsor to upload your package for you.  Sponsors are people who are
+official Debian Developers, and who are willing to criticize and upload your
+packages for you.  Please read the unofficial debian-mentors FAQ at <ulink
+url="http://people.debian.org/~mpalmer/debian-mentors_FAQ.html"></ulink> first.
+</para>
+<para>
+If you wish to be a mentor and/or sponsor, more information is available in
+<xref linkend="newmaint"/> .
+</para>
+</section>
+
+<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
+the information available at the <ulink
+url="http://www.debian.org/devel/join/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
+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.
+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
+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.
+</para>
+<para>
+Before you actually register you should have shown that you can do competent
+work and will be a good contributor.  You show this by submitting patches
+through the Bug Tracking System and having a package sponsored by an existing
+Debian Developer for a while.  Also, we expect that contributors are interested
+in the whole project and not just in maintaining their own packages.  If you
+can help other maintainers by providing further information on a bug or even a
+patch, then do so!
+</para>
+<para>
+Registration requires that you are familiar with Debian's philosophy and
+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
+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
+more information.)
+</para>
+<para>
+If you do not have an OpenPGP key yet, generate one.  Every developer needs an
+OpenPGP key in order to sign and verify package uploads.  You should read the
+manual for the software you are using, since it has much important information
+which is critical to its security.  Many more security failures are due to
+human error than to software failure or high-powered spy techniques.  See <xref
+linkend="key-maint"/> for more information on maintaining your public key.
+</para>
+<para>
+Debian uses the <command>GNU Privacy Guard</command> (package <systemitem
+role="package">gnupg</systemitem> version 1 or better) as its baseline
+standard.  You can use some other implementation of OpenPGP as well.  Note that
+OpenPGP is an open standard based on <ulink
+url="http://www.rfc-editor.org/rfc/rfc2440.txt">RFC 2440</ulink>.
+</para>
+<para>
+You need a version 4 key for use in Debian Development.  Your key length must
+be at least 1024 bits; there is no reason to use a smaller key, and doing so
+would be much less secure.  <footnote><para> Version 4 keys are keys conforming
+to the OpenPGP standard as defined in RFC 2440.  Version 4 is the key type that
+has always been created when using GnuPG.  PGP versions since 5.x also could
+create v4 keys, the other choice having beein pgp 2.6.x compatible v3 keys
+(also called legacy RSA by PGP).  </para> <para> Version 4 (primary) keys can
+either use the RSA or the DSA algorithms, so this has nothing to do with
+GnuPG's question about which kind of key do you want: (1) DSA and Elgamal, (2)
+DSA (sign only), (5) RSA (sign only).  If you don't have any special
+requirements just pick the default.  </para> <para> The easiest way to tell
+whether an existing key is a v4 key or a v3 (or v2) key is to look at the
+fingerprint: Fingerprints of version 4 keys are the SHA-1 hash of some key
+matieral, so they are 40 hex digits, usually grouped in blocks of 4.
+Fingerprints of older key format versions used MD5 and are generally shown in
+blocks of 2 hex digits.  For example if your fingerprint looks like
+<literal>5B00 C96D 5D54 AEE1 206B  AF84 DE7A AF6E 94C0 9C7F</literal>
+then it's a v4 key.  </para> <para> Another possibility is to pipe the key into
+<command>pgpdump</command>, which will say something like Public Key Packet -
+Ver 4.  </para> <para> Also note that your key must be self-signed (i.e.  it
+has to sign all its own user IDs; this prevents user ID tampering).  All modern
+OpenPGP software does that automatically, but if you have an older key you may
+have to manually add those signatures.  </para> </footnote>
+</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:
+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>
+<para>
+Some countries restrict the use of cryptographic software by their citizens.
+This need not impede one's activities as a Debian package maintainer however,
+as it may be perfectly legal to use cryptographic products for authentication,
+rather than encryption purposes.  If you live in a country where use of
+cryptography even for authentication is forbidden then please contact us so we
+can make special arrangements.
+</para>
+<para>
+To apply as a new maintainer, you need an existing Debian Developer to support
+your application (an <emphasis>advocate</emphasis>).  After you have
+contributed to Debian for a while, and you want to apply to become a registered
+developer, an existing developer with whom you have worked over the past months
+has to express their belief that you can contribute to Debian successfully.
+</para>
+<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
+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>.
+</para>
+<para>
+For more details, please consult <ulink
+url="http://www.debian.org/devel/join/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.
+</para>
+</section>
+
+</chapter>
+
diff --git a/pkgs.dbk b/pkgs.dbk
new file mode 100644 (file)
index 0000000..68e24f1
--- /dev/null
+++ b/pkgs.dbk
@@ -0,0 +1,2608 @@
+<?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">
+<chapter id="pkgs">
+<title>Managing Packages</title>
+<para>
+This chapter contains information related to creating, uploading, maintaining,
+and porting packages.
+</para>
+<section id="newpackage">
+<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
+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
+pages</ulink> for more information.
+</para>
+<para>
+Assuming no one else is already working on your prospective package, you must
+then submit a bug report (<xref linkend="submit-bug"/> ) against the
+pseudo-package <systemitem role="package">wnpp</systemitem> describing your
+plan to create a new package, including, but not limiting yourself to, a
+description of the package, the license of the prospective package, and the
+current URL where it can be downloaded from.
+</para>
+<para>
+You should set the subject of the bug to ``ITP: <replaceable>foo</replaceable>
+-- <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
+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).
+</para>
+<para>
+Please include a <literal>Closes:
+bug#<replaceable>nnnnn</replaceable></literal> entry in the changelog of the
+new package in order for the bug report to be automatically closed once the new
+package is installed in the archive (see <xref linkend="upload-bugfix"/> ).
+</para>
+<para>
+When closing security bugs include CVE numbers as well as the Closes: #nnnnn.
+This is useful for the security team to track vulnerabilities.  If an upload is
+made to fix the bug before the advisory ID is known, it is encouraged to modify
+the historical changelog entry with the next upload.  Even in this case, please
+include all available pointers to background information in the original
+changelog entry.
+</para>
+<para>
+There are a number of reasons why we ask maintainers to announce their
+intentions:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+It helps the (potentially new) maintainer to tap into the experience of people
+on the list, and lets them know if anyone else is working on it already.
+</para>
+</listitem>
+<listitem>
+<para>
+It lets other people thinking about working on the package know that there
+already is a volunteer, so efforts may be shared.
+</para>
+</listitem>
+<listitem>
+<para>
+It lets the rest of the maintainers know more about the package than the one
+line description and the usual changelog entry ``Initial release'' that gets
+posted to <literal>debian-devel-changes</literal>.
+</para>
+</listitem>
+<listitem>
+<para>
+It is helpful to the people who live off unstable (and form our first line of
+testers).  We should encourage these people.
+</para>
+</listitem>
+<listitem>
+<para>
+The announcements give maintainers and other interested parties a better feel
+of what is going on, and what is new, in the project.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Please see <ulink url="http://ftp-master.debian.org/REJECT-FAQ.html"></ulink>
+for common rejection reasons for a new package.
+</para>
+</section>
+
+<section id="changelog-entries">
+<title>Recording changes in the package</title>
+<para>
+Changes that you make to the package need to be recorded in the
+<filename>debian/changelog</filename>.  These changes should provide a concise
+description of what was changed, why (if it's in doubt), and note if any bugs
+were closed.  They also record when the package was completed.  This file will
+be installed in
+<filename>/usr/share/doc/<replaceable>package</replaceable>/changelog.Debian.gz</filename>,
+or
+<filename>/usr/share/doc/<replaceable>package</replaceable>/changelog.gz</filename>
+for native packages.
+</para>
+<para>
+The <filename>debian/changelog</filename> file conforms to a certain structure,
+with a number of different fields.  One field of note, the
+<emphasis>distribution</emphasis>, is described in <xref
+linkend="distribution"/> .  More information about the structure of this file
+can be found in the Debian Policy section titled
+<filename>debian/changelog</filename>.
+</para>
+<para>
+Changelog entries can be used to automatically close Debian bugs when the
+package is installed into the archive.  See <xref linkend="upload-bugfix"/> .
+</para>
+<para>
+It is conventional that the changelog entry of a package that contains a new
+upstream version of the software looks like this:
+</para>
+<screen>
+  * new upstream version
+</screen>
+<para>
+There are tools to help you create entries and finalize the
+<filename>changelog</filename> for release — see <xref linkend="devscripts"/>
+and <xref linkend="dpkg-dev-el"/> .
+</para>
+<para>
+See also <xref linkend="bpp-debian-changelog"/> .
+</para>
+</section>
+
+<section id="sanitycheck">
+<title>Testing the package</title>
+<para>
+Before you upload your package, you should do basic testing on it.  At a
+minimum, you should try the following activities (you'll need to have an older
+version of the same Debian package around):
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Install the package and make sure the software works, or upgrade the package
+from an older version to your new version if a Debian package for it already
+exists.
+</para>
+</listitem>
+<listitem>
+<para>
+Run <command>lintian</command> over the package.  You can run
+<command>lintian</command> as follows: <literal>lintian -v
+<replaceable>package-version</replaceable>.changes</literal>.  This will check
+the source package as well as the binary package.  If you don't understand the
+output that <command>lintian</command> generates, try adding the
+<literal>-i</literal> switch, which will cause <command>lintian</command> to
+output a very verbose description of the problem.
+</para>
+<para>
+Normally, a package should <emphasis>not</emphasis> be uploaded if it causes
+lintian to emit errors (they will start with <literal>E</literal>).
+</para>
+<para>
+For more information on <command>lintian</command>, see <xref
+linkend="lintian"/> .
+</para>
+</listitem>
+<listitem>
+<para>
+Optionally run <xref linkend="debdiff"/> to analyze changes from an older
+version, if one exists.
+</para>
+</listitem>
+<listitem>
+<para>
+Downgrade the package to the previous version (if one exists) — this tests
+the <filename>postrm</filename> and <filename>prerm</filename> scripts.
+</para>
+</listitem>
+<listitem>
+<para>
+Remove the package, then reinstall it.
+</para>
+</listitem>
+<listitem>
+<para>
+Copy the source package in a different directory and try unpacking it and
+rebuilding it.  This tests if the package relies on existing files outside of
+it, or if it relies on permissions being preserved on the files shipped inside
+the .diff.gz file.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="sourcelayout">
+<title>Layout of the source package</title>
+<para>
+There are two types of Debian source packages:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+the so-called <emphasis>native</emphasis> packages, where there is no
+distinction between the original sources and the patches applied for Debian
+</para>
+</listitem>
+<listitem>
+<para>
+the (more common) packages where there's an original source tarball file
+accompanied by another file that contains the patches applied for Debian
+</para>
+</listitem>
+</itemizedlist>
+<para>
+For the native packages, the source package includes a Debian source control
+file (<literal>.dsc</literal>) and the source tarball
+(<literal>.tar.gz</literal>).  A source package of a non-native package
+includes a Debian source control file, the original source tarball
+(<literal>.orig.tar.gz</literal>) and the Debian patches
+(<literal>.diff.gz</literal>).
+</para>
+<para>
+Whether a package is native or not is determined when it is built by
+<citerefentry> <refentrytitle>dpkg-buildpackage</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>.  The rest of this section relates
+only to non-native packages.
+</para>
+<para>
+The first time a version is uploaded which corresponds to a particular upstream
+version, the original source tar file should be uploaded and included in the
+<filename>.changes</filename> file.  Subsequently, this very same tar file
+should be used to build the new diffs and <filename>.dsc</filename> files, and
+will not need to be re-uploaded.
+</para>
+<para>
+By default, <command>dpkg-genchanges</command> and
+<command>dpkg-buildpackage</command> will include the original source tar file
+if and only if the Debian revision part of the source version number is 0 or 1,
+indicating a new upstream version.  This behavior may be modified by using
+<literal>-sa</literal> to always include it or <literal>-sd</literal> to always
+leave it out.
+</para>
+<para>
+If no original source is included in the upload, the original source tar-file
+used by <command>dpkg-source</command> when constructing the
+<filename>.dsc</filename> file and diff to be uploaded
+<emphasis>must</emphasis> be byte-for-byte identical with the one already in
+the archive.
+</para>
+<para>
+Please notice that, in non-native packages, permissions on files that are not
+present in the .orig.tar.gz will not be preserved, as diff does not store file
+permissions in the patch.
+</para>
+</section>
+
+<section id="distribution">
+<title>Picking a distribution</title>
+<para>
+Each upload needs to specify which distribution the package is intended for.
+The package build process extracts this information from the first line of the
+<filename>debian/changelog</filename> file and places it in the
+<literal>Distribution</literal> field of the <literal>.changes</literal> file.
+</para>
+<para>
+There are several possible values for this field: `stable', `unstable',
+`testing-proposed-updates' and `experimental'.  Normally, packages are uploaded
+into <emphasis>unstable</emphasis>.
+</para>
+<para>
+Actually, there are two other possible distributions: `stable-security' and
+`testing-security', but read <xref linkend="bug-security"/> for more
+information on those.
+</para>
+<para>
+It is not possible to upload a package into several distributions at the same
+time.
+</para>
+<section id="upload-stable">
+<title>Special case: uploads to the <emphasis>stable</emphasis> distribution</title>
+<para>
+Uploading to <emphasis>stable</emphasis> means that the package will transfered
+to the <emphasis>p-u-new</emphasis>-queue for review by the stable release
+managers, and if approved will be installed in
+<filename>stable-proposed-updates</filename> directory of the Debian archive.
+From there, it will be included in <emphasis>stable</emphasis> with the next
+point release.
+</para>
+<para>
+Extra care should be taken when uploading to <emphasis>stable</emphasis>.
+Basically, a package should only be uploaded to stable if one of the following
+happens:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+a truly critical functionality problem
+</para>
+</listitem>
+<listitem>
+<para>
+the package becomes uninstallable
+</para>
+</listitem>
+<listitem>
+<para>
+a released architecture lacks the package
+</para>
+</listitem>
+</itemizedlist>
+<para>
+In the past, uploads to <emphasis>stable</emphasis> were used to address
+security problems as well.  However, this practice is deprecated, as uploads
+used for Debian security advisories are automatically copied to the appropriate
+<filename>proposed-updates</filename> archive when the advisory is released.
+See <xref linkend="bug-security"/> for detailed information on handling
+security problems.
+</para>
+<para>
+Changing anything else in the package that isn't important is discouraged,
+because even trivial fixes can cause bugs later on.
+</para>
+<para>
+Packages uploaded to <emphasis>stable</emphasis> need to be compiled on systems
+running <emphasis>stable</emphasis>, so that their dependencies are limited to
+the libraries (and other packages) available in <emphasis>stable</emphasis>;
+for example, a package uploaded to <emphasis>stable</emphasis> that depends on
+a library package that only exists in unstable will be rejected.  Making
+changes to dependencies of other packages (by messing with
+<literal>Provides</literal> or shlibs files), possibly making those other
+packages uninstallable, is strongly discouraged.
+</para>
+<para>
+The Release Team (which can be reached at
+<email>debian-release@lists.debian.org</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
+<emphasis>stable</emphasis>, because otherwise the package won't be considered
+for inclusion.
+</para>
+<para>
+It's best practice to speak with the stable release manager
+<emphasis>before</emphasis> uploading to
+<emphasis>stable</emphasis>/<emphasis>stable-proposed-updates</emphasis>, so
+that the uploaded package fits the needs of the next point release.
+</para>
+</section>
+
+<section id="upload-t-p-u">
+<title>Special case: uploads to <emphasis>testing/testing-proposed-updates</emphasis></title>
+<para>
+Please see the information in the <link linkend="t-p-u">testing
+section</link> for details.
+</para>
+</section>
+
+</section>
+
+<section id="upload">
+<title>Uploading a package</title>
+<section id="upload-ftp-master">
+<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
+the directory <ulink
+url="ftp://ftp-master.debian.org/pub/UploadQueue/">/pub/UploadQueue/</ulink>.
+To get the files processed there, they need to be signed with a key in the
+debian keyring.
+</para>
+<para>
+Please note that you should transfer the changes file last.  Otherwise, your
+upload may be rejected because the archive maintenance software will parse the
+changes file and see that not all files have been uploaded.
+</para>
+<para>
+You may also find the Debian packages <xref linkend="dupload"/> or <xref
+linkend="dput"/> useful when uploading packages.  These handy programs help
+automate the process of uploading packages into Debian.
+</para>
+<para>
+For removing packages, please see the README file in that ftp directory, and
+the Debian package <xref linkend="dcut"/> .
+</para>
+</section>
+
+<section id="upload-non-us">
+<title>Uploading to <literal>non-US</literal></title>
+<para>
+<emphasis>Note:</emphasis> non-us was discontinued with the release of sarge.
+</para>
+</section>
+
+<section id="delayed-incoming">
+<title>Delayed uploads</title>
+<para>
+Delayed uploads are done for the moment via the delayed queue at gluck.  The
+upload-directory is <literal>gluck:~tfheen/DELAYED/[012345678]-day</literal>.
+0-day is uploaded multiple times per day to ftp-master.
+</para>
+<para>
+With a fairly recent dput, this section
+</para>
+<screen>
+[tfheen_delayed]
+method = scp
+fqdn = gluck.debian.org
+incoming = ~tfheen
+</screen>
+<para>
+in ~/.dput.cf should work fine for uploading to the DELAYED queue.
+</para>
+<para>
+<emphasis>Note:</emphasis> Since this upload queue goes to
+<literal>ftp-master</literal>, the prescription found in <xref
+linkend="upload-ftp-master"/> applies here as well.
+</para>
+</section>
+
+<section id="s5.6.4">
+<title>Security uploads</title>
+<para>
+Do <emphasis role="strong">NOT</emphasis> upload a package to the security
+upload queue (oldstable-security, stable-security, etc.) without prior
+authorization from the security team.  If the package does not exactly meet the
+team's requirements, it will cause many problems and delays in dealing with the
+unwanted upload.  For details, please see section <xref
+linkend="bug-security"/> .
+</para>
+</section>
+
+<section id="s5.6.5">
+<title>Other upload queues</title>
+<para>
+The scp queues on ftp-master, and security are mostly unusable due to the login
+restrictions on those hosts.
+</para>
+<para>
+The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are currently
+down.  Work is underway to resurrect them.
+</para>
+<para>
+The queues on master.debian.org, samosa.debian.org, master.debian.or.jp, and
+ftp.chiark.greenend.org.uk are down permanently, and will not be resurrected.
+The queue in Japan will be replaced with a new queue on hp.debian.or.jp some
+day.
+</para>
+<para>
+For the time being, the anonymous ftp queue on auric.debian.org (the former
+ftp-master) works, but it is deprecated and will be removed at some point in
+the future.
+</para>
+</section>
+
+<section id="upload-notification">
+<title>Notification that a new package has been installed</title>
+<para>
+The Debian archive maintainers are responsible for handling package uploads.
+For the most part, uploads are automatically handled on a daily basis by the
+archive maintenance tools, <command>katie</command>.  Specifically, updates to
+existing packages to the `unstable' distribution are handled automatically.  In
+other cases, notably new packages, placing the uploaded package into the
+distribution is handled manually.  When uploads are handled manually, the
+change to the archive may take up to a month to occur.  Please be patient.
+</para>
+<para>
+In any case, you will receive an email notification indicating that the package
+has been added to the archive, which also indicates which bugs will be closed
+by the upload.  Please examine this notification carefully, checking if any
+bugs you meant to close didn't get triggered.
+</para>
+<para>
+The installation notification also includes information on what section the
+package was inserted into.  If there is a disparity, you will receive a
+separate email notifying you of that.  Read on below.
+</para>
+<para>
+Note that if you upload via queues, the queue daemon software will also send
+you a notification by email.
+</para>
+</section>
+
+</section>
+
+<section id="override-file">
+<title>Specifying the package section, subsection and priority</title>
+<para>
+The <filename>debian/control</filename> file's <literal>Section</literal> and
+<literal>Priority</literal> fields do not actually specify where the file will
+be placed in the archive, nor its priority.  In order to retain the overall
+integrity of the archive, it is the archive maintainers who have control over
+these fields.  The values in the <filename>debian/control</filename> file are
+actually just hints.
+</para>
+<para>
+The archive maintainers keep track of the canonical sections and priorities for
+packages in the <emphasis>override file</emphasis>.  If there is a disparity
+between the <emphasis>override file</emphasis> and the package's fields as
+indicated in <filename>debian/control</filename>, then you will receive an
+email noting the divergence when the package is installed into the archive.
+You can either correct your <filename>debian/control</filename> file for your
+next upload, or else you may wish to make a change in the <emphasis>override
+file</emphasis>.
+</para>
+<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>
+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>
+<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>.
+</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>.
+</para>
+</section>
+
+<section id="bug-handling">
+<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
+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
+developers</ulink>.  This includes closing bugs, sending followup messages,
+assigning severities and tags, marking bugs as forwarded, and other issues.
+</para>
+<para>
+Operations such as reassigning bugs to other packages, merging separate bug
+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
+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
+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>.
+</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
+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>
+Some find it useful to get periodic reports on open bugs.  You can add a cron
+job such as the following if you want to get a weekly email outlining all the
+open bugs against your packages:
+</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
+</screen>
+<para>
+Replace <replaceable>address</replaceable> with your official Debian maintainer
+address.
+</para>
+</section>
+
+<section id="bug-answering">
+<title>Responding to bugs</title>
+<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
+don't remember the submitter email address, you can use the
+<email>123-submitter@bugs.debian.org</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>).
+</para>
+<para>
+If you get a bug which mentions FTBFS, this means Fails to build from source.
+Porters frequently use this acronym.
+</para>
+<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
+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
+will not receive any information about why the bug was closed.
+</para>
+</section>
+
+<section id="bug-housekeeping">
+<title>Bug housekeeping</title>
+<para>
+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
+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
+documentation</ulink>.  This section contains some guidelines for managing your
+own bugs, based on the collective Debian developer experience.
+</para>
+<para>
+Filing bugs for problems that you find in other packages is one of the civic
+obligations of maintainership, see <xref linkend="submit-bug"/> for details.
+However, handling the bugs in your own packages is even more important.
+</para>
+<para>
+Here's a list of steps that you may follow to handle a bug report:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Decide whether the report corresponds to a real bug or not.  Sometimes users
+are just calling a program in the wrong way because they haven't read the
+documentation.  If you diagnose this, just close the bug with enough
+information to let the user correct their problem (give pointers to the good
+documentation and so on).  If the same report comes up again and again you may
+ask yourself if the documentation is good enough or if the program shouldn't
+detect its misuse in order to give an informative error message.  This is an
+issue that may need to be brought up with the upstream author.
+</para>
+<para>
+If the bug submitter disagrees with your decision to close the bug, they may
+reopen it until you find an agreement on how to handle it.  If you don't find
+any, you may want to tag the bug <literal>wontfix</literal> to let people know
+that the bug exists but that it won't be corrected.  If this situation is
+unacceptable, you (or the submitter) may want to require a decision of the
+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
+procedure</ulink>.
+</para>
+</listitem>
+<listitem>
+<para>
+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
+maintainer(s) of the package the bug is reassigned to know why you reassigned
+it.
+</para>
+<para>
+Sometimes you also have to adjust the severity of the bug so that it matches
+our definition of the severity.  That's because people tend to inflate the
+severity of bugs to make sure their bugs are fixed quickly.  Some bugs may even
+be dropped to wishlist severity when the requested change is just cosmetic.
+</para>
+</listitem>
+<listitem>
+<para>
+If the bug is real but the same problem has already been reported by someone
+else, then the two relevant bug reports should be merged into one using the
+merge command of the BTS.  In this way, when the bug is fixed, all of the
+submitters will be informed of this.  (Note, however, that emails sent to one
+bug report's submitter won't automatically be sent to the other report's
+submitter.) For more details on the technicalities of the merge command and its
+relative, the unmerge command, see the BTS control server documentation.
+</para>
+</listitem>
+<listitem>
+<para>
+The bug submitter may have forgotten to provide some information, in which case
+you have to ask them for the required information.  You may use the
+<literal>moreinfo</literal> tag to mark the bug as such.  Moreover if you can't
+reproduce the bug, you tag it <literal>unreproducible</literal>.  Anyone who
+can reproduce the bug is then invited to provide more information on how to
+reproduce it.  After a few months, if this information has not been sent by
+someone, the bug may be closed.
+</para>
+</listitem>
+<listitem>
+<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
+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
+the required skills you can prepare a patch that fixes the bug and send it to
+the author at the same time.  Make sure to send the patch to the BTS and to tag
+the bug as <literal>patch</literal>.
+</para>
+</listitem>
+<listitem>
+<para>
+If you have fixed a bug in your local copy, or if a fix has been committed to
+the CVS repository, you may tag the bug as <literal>pending</literal> to let
+people know that the bug is corrected and that it will be closed with the next
+upload (add the <literal>closes:</literal> in the
+<filename>changelog</filename>).  This is particularly useful if you are
+several developers working on the same package.
+</para>
+</listitem>
+<listitem>
+<para>
+Once a corrected package is available in the <emphasis>unstable</emphasis>
+distribution, you can close the bug.  This can be done automatically, read
+<xref linkend="upload-bugfix"/> .
+</para>
+</listitem>
+</orderedlist>
+</section>
+
+<section id="upload-bugfix">
+<title>When bugs are closed by new uploads</title>
+<para>
+As bugs and problems are fixed in your packages, it is your responsibility as
+the package maintainer to close these bugs.  However, you should not close a
+bug until the package which fixes the bug has been accepted into the Debian
+archive.  Therefore, once you get notification that your updated package has
+been installed into the archive, you can and should close the bug in the BTS.
+Also, the bug should be closed with the correct version.
+</para>
+<para>
+However, it's possible to avoid having to manually close bugs after the upload
+— just list the fixed bugs in your <filename>debian/changelog</filename>
+file, following a certain syntax, and the archive maintenance software will
+close the bugs for you.  For example:
+</para>
+<screen>
+-cannon (3.1415) unstable; urgency=low
+
+  * Frobbed with options (closes: Bug#98339)
+  * Added safety to prevent operator dismemberment, closes: bug#98765,
+    bug#98713, #98714.
+  * Added man page. Closes: #98725.
+</screen>
+<para>
+Technically speaking, the following Perl regular expression describes how bug
+closing changelogs are identified:
+</para>
+<screen>
+  /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
+</screen>
+<para>
+We prefer the <literal>closes: #<replaceable>XXX</replaceable></literal>
+syntax, as it is the most concise entry and the easiest to integrate with the
+text of the <filename>changelog</filename>.  Unless specified different by the
+<replaceable>-v</replaceable>-switch to <command>dpkg-buildpackage</command>,
+only the bugs closed in the most recent changelog entry are closed (basically,
+exactly the bugs mentioned in the changelog-part in the
+<filename>.changes</filename> file are closed).
+</para>
+<para>
+Historically, uploads identified as <link linkend="nmu">Non-maintainer
+upload (NMU)</link> were tagged <literal>fixed</literal> instead of being
+closed, but that practice was ceased with the advent of version-tracking.  The
+same applied to the tag <literal>fixed-in-experimental</literal>.
+</para>
+<para>
+If you happen to mistype a bug number or forget a bug in the changelog entries,
+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
+fixed by your upload, email the <filename>.changes</filename> file to
+<email>XXX-done@bugs.debian.org</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.
+</para>
+<para>
+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
+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>
+<para>
+For general information on how to write your changelog entries, see <xref
+linkend="bpp-debian-changelog"/> .
+</para>
+</section>
+
+<section id="bug-security">
+<title>Handling security-related bugs</title>
+<para>
+Due to their sensitive nature, security-related bugs must be handled carefully.
+The Debian Security Team exists to coordinate this activity, keeping track of
+outstanding security problems, helping maintainers with security problems or
+fixing them themselves, sending security advisories, and maintaining
+security.debian.org.
+</para>
+<para>
+When you become aware of a security-related bug in a Debian package, whether or
+not you are the maintainer, collect pertinent information about the problem,
+and promptly contact the security team at
+<email>team@security.debian.org</email> as soon as possible.  <emphasis
+role="strong">DO NOT UPLOAD</emphasis> any packages for stable; the security
+team will do that.  Useful information includes, for example:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Which versions of the package are known to be affected by the bug.  Check each
+version that is present in a supported Debian release, as well as testing and
+unstable.
+</para>
+</listitem>
+<listitem>
+<para>
+The nature of the fix, if any is available (patches are especially helpful)
+</para>
+</listitem>
+<listitem>
+<para>
+Any fixed packages that you have prepared yourself (send only the
+<literal>.diff.gz</literal> and <literal>.dsc</literal> files and read <xref
+linkend="bug-security-building"/> first)
+</para>
+</listitem>
+<listitem>
+<para>
+Any assistance you can provide to help with testing (exploits, regression
+testing, etc.)
+</para>
+</listitem>
+<listitem>
+<para>
+Any information needed for the advisory (see <xref
+linkend="bug-security-advisories"/> )
+</para>
+</listitem>
+</itemizedlist>
+<section id="bug-security-confidentiality">
+<title>Confidentiality</title>
+<para>
+Unlike most other activities within Debian, information about security issues
+must sometimes be kept private for a time.  This allows software distributors
+to coordinate their disclosure in order to minimize their users' exposure.
+Whether this is the case depends on the nature of the problem and corresponding
+fix, and whether it is already a matter of public knowledge.
+</para>
+<para>
+There are several ways developers can learn of a security problem:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+they notice it on a public forum (mailing list, web site, etc.)
+</para>
+</listitem>
+<listitem>
+<para>
+someone files a bug report
+</para>
+</listitem>
+<listitem>
+<para>
+someone informs them via private email
+</para>
+</listitem>
+</itemizedlist>
+<para>
+In the first two cases, the information is public and it is important to have a
+fix as soon as possible.  In the last case, however, it might not be public
+information.  In that case there are a few possible options for dealing with
+the problem:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If the security exposure is minor, there is sometimes no need to keep the
+problem a secret and a fix should be made and released.
+</para>
+</listitem>
+<listitem>
+<para>
+If the problem is severe, it is preferable to share the information with other
+vendors and coordinate a release.  The security team keeps in contact with the
+various organizations and individuals and can take care of that.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+In all cases if the person who reports the problem asks that it not be
+disclosed, such requests should be honored, with the obvious exception of
+informing the security team in order that a fix may be produced for a stable
+release of Debian.  When sending confidential information to the security team,
+be sure to mention this fact.
+</para>
+<para>
+Please note that if secrecy is needed you may not upload a fix to unstable (or
+anywhere else, such as a public CVS repository).  It is not sufficient to
+obfuscate the details of the change, as the code itself is public, and can (and
+will) be examined by the general public.
+</para>
+<para>
+There are two reasons for releasing information even though secrecy is
+requested: the problem has been known for a while, or the problem or exploit
+has become public.
+</para>
+</section>
+
+<section id="bug-security-advisories">
+<title>Security Advisories</title>
+<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
+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
+an advisory includes:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+A description of the problem and its scope, including:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The type of problem (privilege escalation, denial of service, etc.)
+</para>
+</listitem>
+<listitem>
+<para>
+What privileges may be gained, and by whom (if any)
+</para>
+</listitem>
+<listitem>
+<para>
+How it can be exploited
+</para>
+</listitem>
+<listitem>
+<para>
+Whether it is remotely or locally exploitable
+</para>
+</listitem>
+<listitem>
+<para>
+How the problem was fixed
+</para>
+</listitem>
+</itemizedlist>
+<para>
+This information allows users to assess the threat to their systems.
+</para>
+</listitem>
+<listitem>
+<para>
+Version numbers of affected packages
+</para>
+</listitem>
+<listitem>
+<para>
+Version numbers of fixed packages
+</para>
+</listitem>
+<listitem>
+<para>
+Information on where to obtain the updated packages (usually from the Debian
+security archive)
+</para>
+</listitem>
+<listitem>
+<para>
+References to upstream advisories, <ulink
+url="http://cve.mitre.org">CVE</ulink> identifiers, and any other information
+useful in cross-referencing the vulnerability
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="bug-security-building">
+<title>Preparing packages to address security issues</title>
+<para>
+One way that you can assist the security team in their duties is to provide
+them with fixed packages suitable for a security advisory for the stable Debian
+release.
+</para>
+<para>
+When an update is made to the stable release, care must be taken to avoid
+changing system behavior or introducing new bugs.  In order to do this, make as
+few changes as possible to fix the bug.  Users and administrators rely on the
+exact behavior of a release once it is made, so any change that is made might
+break someone's system.  This is especially true of libraries: make sure you
+never change the API or ABI, no matter how small the change.
+</para>
+<para>
+This means that moving to a new upstream version is not a good solution.
+Instead, the relevant changes should be back-ported to the version present in
+the current stable Debian release.  Generally, upstream maintainers are willing
+to help if needed.  If not, the Debian security team may be able to help.
+</para>
+<para>
+In some cases, it is not possible to back-port a security fix, for example when
+large amounts of source code need to be modified or rewritten.  If this
+happens, it may be necessary to move to a new upstream version.  However, this
+is only done in extreme situations, and you must always coordinate that with
+the security team beforehand.
+</para>
+<para>
+Related to this is another important guideline: always test your changes.  If
+you have an exploit available, try it and see if it indeed succeeds on the
+unpatched package and fails on the fixed package.  Test other, normal actions
+as well, as sometimes a security fix can break seemingly unrelated features in
+subtle ways.
+</para>
+<para>
+Do <emphasis role="strong">NOT</emphasis> include any changes in your package
+which are not directly related to fixing the vulnerability.  These will only
+need to be reverted, and this wastes time.  If there are other bugs in your
+package that you would like to fix, make an upload to proposed-updates in the
+usual way, after the security advisory is issued.  The security update
+mechanism is not a means for introducing changes to your package which would
+otherwise be rejected from the stable release, so please do not attempt to do
+this.
+</para>
+<para>
+Review and test your changes as much as possible.  Check the differences from
+the previous version repeatedly (<command>interdiff</command> from the
+<systemitem role="package">patchutils</systemitem> package and
+<command>debdiff</command> from <systemitem
+role="package">devscripts</systemitem> are useful tools for this, see <xref
+linkend="debdiff"/> ).
+</para>
+<para>
+Be sure to verify the following items:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Target the right distribution in your <filename>debian/changelog</filename>.
+For stable this is <literal>stable-security</literal> and for testing this is
+<literal>testing-security</literal>, and for the previous stable release, this
+is <literal>oldstable-security</literal>.  Do not target
+<replaceable>distribution</replaceable>-proposed-updates or
+<literal>stable</literal>!
+</para>
+</listitem>
+<listitem>
+<para>
+The upload should have urgency=high.
+</para>
+</listitem>
+<listitem>
+<para>
+Make descriptive, meaningful changelog entries.  Others will rely on them to
+determine whether a particular bug was fixed.  Always include an external
+reference, preferably a CVE identifier, so that it can be cross-referenced.
+Include the same information in the changelog for unstable, so that it is clear
+that the same bug was fixed, as this is very helpful when verifying that the
+bug is fixed in the next stable release.  If a CVE identifier has not yet been
+assigned, the security team will request one so that it can be included in the
+package and in the advisory.
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure the version number is proper.  It must be greater than the current
+package, but less than package versions in later distributions.  If in doubt,
+test it with <literal>dpkg --compare-versions</literal>.  Be careful not to
+re-use a version number that you have already used for a previous upload.  For
+<emphasis>testing</emphasis>, there must be a higher version in
+<emphasis>unstable</emphasis>.  If there is none yet (for example, if
+<emphasis>testing</emphasis> and <emphasis>unstable</emphasis> have the same
+version) you must upload a new version to unstable first.
+</para>
+</listitem>
+<listitem>
+<para>
+Do not make source-only uploads if your package has any binary-all packages (do
+not use the <literal>-S</literal> option to
+<command>dpkg-buildpackage</command>).  The <command>buildd</command>
+infrastructure will not build those.  This point applies to normal package
+uploads as well.
+</para>
+</listitem>
+<listitem>
+<para>
+Unless the upstream source has been uploaded to security.debian.org before (by
+a previous security update), build the upload with full upstream source
+(<literal>dpkg-buildpackage -sa</literal>).  If there has been a previous
+upload to security.debian.org with the same upstream version, you may upload
+without upstream source (<literal>dpkg-buildpackage -sd</literal>).
+</para>
+</listitem>
+<listitem>
+<para>
+Be sure to use the exact same <filename>*.orig.tar.gz</filename> as used in the
+normal archive, otherwise it is not possible to move the security fix into the
+main archives later.
+</para>
+</listitem>
+<listitem>
+<para>
+Build the package on a clean system which only has packages installed from the
+distribution you are building for.  If you do not have such a system yourself,
+you can use a debian.org machine (see <xref linkend="server-machines"/> ) or
+setup a chroot (see <xref linkend="pbuilder"/> and <xref
+linkend="debootstrap"/> ).
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="bug-security-upload">
+<title>Uploading the fixed package</title>
+<para>
+Do <emphasis role="strong">NOT</emphasis> upload a package to the security
+upload queue (oldstable-security, stable-security, etc.) without prior
+authorization from the security team.  If the package does not exactly meet the
+team's requirements, it will cause many problems and delays in dealing with the
+unwanted upload.
+</para>
+<para>
+Do <emphasis role="strong">NOT</emphasis> upload your fix to proposed-updates
+without coordinating with the security team.  Packages from security.debian.org
+will be copied into the proposed-updates directory automatically.  If a package
+with the same or a higher version number is already installed into the archive,
+the security update will be rejected by the archive system.  That way, the
+stable distribution will end up without a security update for this package
+instead.
+</para>
+<para>
+Once you have created and tested the new package and it has been approved by
+the security team, it needs to be uploaded so that it can be installed in the
+archives.  For security uploads, the place to upload to is
+<literal>ftp://security-master.debian.org/pub/SecurityUploadQueue/</literal> .
+</para>
+<para>
+Once an upload to the security queue has been accepted, the package will
+automatically be rebuilt for all architectures and stored for verification by
+the security team.
+</para>
+<para>
+Uploads which are waiting for acceptance or verification are only accessible by
+the security team.  This is necessary since there might be fixes for security
+problems that cannot be disclosed yet.
+</para>
+<para>
+If a member of the security team accepts a package, it will be installed on
+security.debian.org as well as proposed for the proper
+<replaceable>distribution</replaceable>-proposed-updates on ftp-master.
+</para>
+</section>
+
+</section>
+
+</section>
+
+<section id="archive-manip">
+<title>Moving, removing, renaming, adopting, and orphaning packages</title>
+<para>
+Some archive manipulation operations are not automated in the Debian upload
+process.  These procedures should be manually followed by maintainers.  This
+chapter gives guidelines on what to do in these cases.
+</para>
+<section id="moving-pkgs">
+<title>Moving packages</title>
+<para>
+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
+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
+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
+the rest of the package.  If your new section is valid, it will be moved
+automatically.  If it does not, then contact the ftpmasters in order to
+understand what happened.
+</para>
+<para>
+If, on the other hand, you need to change the <emphasis>subsection</emphasis>
+of one of your packages (e.g., ``devel'', ``admin''), the procedure is slightly
+different.  Correct the subsection as found in the control file of the package,
+and re-upload that.  Also, you'll need to get the override file updated, as
+described in <xref linkend="override-file"/> .
+</para>
+</section>
+
+<section id="removing-pkgs">
+<title>Removing packages</title>
+<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;
+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
+<emphasis>experimental</emphasis>.  Packages are not removed from
+<emphasis>testing</emphasis> directly.  Rather, they will be removed
+automatically after the package has been removed from
+<emphasis>unstable</emphasis> and no package in <emphasis>testing</emphasis>
+depends on it.
+</para>
+<para>
+There is one exception when an explicit removal request is not necessary: If a
+(source or binary) package is an orphan, it will be removed semi-automatically.
+For a binary-package, this means if there is no longer any source package
+producing this binary package; if the binary package is just no longer produced
+on some architectures, a removal request is still necessary.  For a
+source-package, this means that all binary packages it refers to have been
+taken over by another source package.
+</para>
+<para>
+In your removal request, you have to detail the reasons justifying the request.
+This is to avoid unwanted removals and to keep a trace of why a package has
+been removed.  For example, you can provide the name of the package that
+supersedes the one to be removed.
+</para>
+<para>
+Usually you only ask for the removal of a package maintained by yourself.  If
+you want to remove another package, you have to get the approval of its
+maintainer.
+</para>
+<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>.
+</para>
+<para>
+If in doubt concerning whether a package is disposable, email
+<email>debian-devel@lists.debian.org</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>.
+</para>
+<para>
+Once the package has been removed, the package's bugs should be handled.  They
+should either be reassigned to another package in the case where the actual
+code has evolved into another package (e.g.  <literal>libfoo12</literal> was
+removed because <literal>libfoo13</literal> supersedes it) or closed if the
+software is simply no longer part of Debian.
+</para>
+<section id="s5.9.2.1">
+<title>Removing packages from <filename>Incoming</filename></title>
+<para>
+In the past, it was possible to remove packages from
+<filename>incoming</filename>.  However, with the introduction of the new
+incoming system, this is no longer possible.  Instead, you have to upload a new
+revision of your package with a higher version than the package you want to
+replace.  Both versions will be installed in the archive but only the higher
+version will actually be available in <emphasis>unstable</emphasis> since the
+previous version will immediately be replaced by the higher.  However, if you
+do proper testing of your packages, the need to replace a package should not
+occur too often anyway.
+</para>
+</section>
+
+</section>
+
+<section id="s5.9.3">
+<title>Replacing or renaming packages</title>
+<para>
+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
+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
+the package with the obsolete name.  Do not forget to properly reassign the
+package's bugs at the same time.
+</para>
+<para>
+At other times, you may make a mistake in constructing your package and wish to
+replace it.  The only way to do this is to increase the version number and
+upload a new version.  The old version will be expired in the usual manner.
+Note that this applies to each part of your package, including the sources: if
+you wish to replace the upstream source tarball of your package, you will need
+to upload it with a different version.  An easy possibility is to replace
+<filename>foo_1.00.orig.tar.gz</filename> with
+<filename>foo_1.00+0.orig.tar.gz</filename>.  This restriction gives each file
+on the ftp site a unique name, which helps to ensure consistency across the
+mirror network.
+</para>
+</section>
+
+<section id="orphaning">
+<title>Orphaning a package</title>
+<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 &lt;packages@qa.debian.org&gt;</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
+description</replaceable></literal> indicating that the package is now
+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
+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>
+<para>
+If you just intend to give the package away, but you can keep maintainership
+for the moment, then you should instead submit a bug against <systemitem
+role="package">wnpp</systemitem> and title it <literal>RFA:
+<replaceable>package</replaceable> -- <replaceable>short
+description</replaceable></literal>.  <literal>RFA</literal> stands for
+<emphasis>Request For Adoption</emphasis>.
+</para>
+<para>
+More information is on the <ulink url="http://www.debian.org/devel/wnpp/">WNPP
+web pages</ulink>.
+</para>
+</section>
+
+<section id="adopting">
+<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
+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.
+</para>
+<para>
+It is not OK to simply take over a package that you feel is neglected — that
+would be package hijacking.  You can, of course, contact the current maintainer
+and ask them if you may take over the package.  If you have reason to believe a
+maintainer has gone AWOL (absent without leave), see <xref linkend="mia-qa"/> .
+</para>
+<para>
+Generally, you may not take over the package without the assent of the current
+maintainer.  Even if they ignore you, that is still not grounds to take over a
+package.  Complaints about maintainers should be brought up on the developers'
+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
+page</ulink> for more information).
+</para>
+<para>
+If you take over an old package, you probably want to be listed as the
+package's official maintainer in the bug system.  This will happen
+automatically once you upload a new version with an updated
+<literal>Maintainer:</literal> field, although it can take a few hours after
+the upload is done.  If you do not expect to upload a new version for a while,
+you can use <xref linkend="pkg-tracking-system"/> to get the bug reports.
+However, make sure that the old maintainer has no problem with the fact that
+they will continue to receive the bugs during that time.
+</para>
+</section>
+
+</section>
+
+<section id="porting">
+<title>Porting and being ported</title>
+<para>
+Debian supports an ever-increasing number of architectures.  Even if you are
+not a porter, and you don't use any architecture but one, it is part of your
+duty as a maintainer to be aware of issues of portability.  Therefore, even if
+you are not a porter, you should read most of this chapter.
+</para>
+<para>
+Porting is the act of building Debian packages for architectures that are
+different from the original architecture of the package maintainer's binary
+package.  It is a unique and essential activity.  In fact, porters do most of
+the actual compiling of Debian packages.  For instance, for a single
+<emphasis>i386</emphasis> binary package, there must be a recompile for each
+architecture, which amounts to 12 more builds.
+</para>
+<section id="kind-to-porters">
+<title>Being kind to porters</title>
+<para>
+Porters have a difficult and unique task, since they are required to deal with
+a large volume of packages.  Ideally, every source package should build right
+out of the box.  Unfortunately, this is often not the case.  This section
+contains a checklist of ``gotchas'' often committed by Debian maintainers —
+common problems which often stymie porters, and make their jobs unnecessarily
+difficult.
+</para>
+<para>
+The first and most important thing is to respond quickly to bug or issues
+raised by porters.  Please treat porters with courtesy, as if they were in fact
+co-maintainers of your package (which, in a way, they are).  Please be tolerant
+of succinct or even unclear bug reports; do your best to hunt down whatever the
+problem is.
+</para>
+<para>
+By far, most of the problems encountered by porters are caused by
+<emphasis>packaging bugs</emphasis> in the source packages.  Here is a
+checklist of things you should check or be aware of.
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Make sure that your <literal>Build-Depends</literal> and
+<literal>Build-Depends-Indep</literal> settings in
+<filename>debian/control</filename> are set properly.  The best way to validate
+this is to use the <systemitem role="package">debootstrap</systemitem> package
+to create an unstable chroot environment (see <xref linkend="debootstrap"/> ).
+Within that chrooted environment, install the <systemitem
+role="package">build-essential</systemitem> package and any package
+dependencies mentioned in <literal>Build-Depends</literal> and/or
+<literal>Build-Depends-Indep</literal>.  Finally, try building your package
+within that chrooted environment.  These steps can be automated by the use of
+the <command>pbuilder</command> program which is provided by the package of the
+same name (see <xref linkend="pbuilder"/> ).
+</para>
+<para>
+If you can't set up a proper chroot, <command>dpkg-depcheck</command> may be of
+assistance (see <xref linkend="dpkg-depcheck"/> ).
+</para>
+<para>
+See the <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy
+Manual</ulink> for instructions on setting build dependencies.
+</para>
+</listitem>
+<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
+Manual</ulink>.  Setting your architecture to ``i386'' is usually incorrect.
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure your source package is correct.  Do <literal>dpkg-source -x
+<replaceable>package</replaceable>.dsc</literal> to make sure your source
+package unpacks properly.  Then, in there, try building your package from
+scratch with <command>dpkg-buildpackage</command>.
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure you don't ship your source package with the
+<filename>debian/files</filename> or <filename>debian/substvars</filename>
+files.  They should be removed by the `clean' target of
+<filename>debian/rules</filename>.
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure you don't rely on locally installed or hacked configurations or
+programs.  For instance, you should never be calling programs in
+<filename>/usr/local/bin</filename> or the like.  Try not to rely on programs
+being setup in a special way.  Try building your package on another machine,
+even if it's the same architecture.
+</para>
+</listitem>
+<listitem>
+<para>
+Don't depend on the package you're building being installed already (a sub-case
+of the above issue).
+</para>
+</listitem>
+<listitem>
+<para>
+Don't rely on the compiler being a certain version, if possible.  If not, then
+make sure your build dependencies reflect the restrictions, although you are
+probably asking for trouble, since different architectures sometimes
+standardize on different compilers.
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure your debian/rules contains separate ``binary-arch'' and
+``binary-indep'' targets, as the Debian Policy Manual requires.  Make sure that
+both targets work independently, that is, that you can call the target without
+having called the other before.  To test this, try to run
+<literal>dpkg-buildpackage -B</literal>.
+</para>
+</listitem>
+</orderedlist>
+</section>
+
+<section id="porter-guidelines">
+<title>Guidelines for porter uploads</title>
+<para>
+If the package builds out of the box for the architecture to be ported to, you
+are in luck and your job is easy.  This section applies to that case; it
+describes how to build and upload your binary package so that it is properly
+installed into the archive.  If you do have to patch the package in order to
+get it to compile for the other architecture, you are actually doing a source
+NMU, so consult <xref linkend="nmu-guidelines"/> instead.
+</para>
+<para>
+For a porter upload, no changes are being made to the source.  You do not need
+to touch any of the files in the source package.  This includes
+<filename>debian/changelog</filename>.
+</para>
+<para>
+The way to invoke <command>dpkg-buildpackage</command> is as
+<literal>dpkg-buildpackage -B
+-m<replaceable>porter-email</replaceable></literal>.  Of course, set
+<replaceable>porter-email</replaceable> to your email address.  This will do a
+binary-only build of only the architecture-dependent portions of the package,
+using the `binary-arch' target in <filename>debian/rules</filename>.
+</para>
+<para>
+If you are working on a Debian machine for your porting efforts and you need to
+sign your upload locally for its acceptance in the archive, you can run
+<command>debsign</command> on your <filename>.changes</filename> file to have
+it signed conveniently, or use the remote signing mode of
+<command>dpkg-sig</command>.
+</para>
+<section id="binary-only-nmu">
+<title>Recompilation or binary-only NMU</title>
+<para>
+Sometimes the initial porter upload is problematic because the environment in
+which the package was built was not good enough (outdated or obsolete library,
+bad compiler, ...).  Then you may just need to recompile it in an updated
+environment.  However, you have to bump the version number in this case, so
+that the old bad package can be replaced in the Debian archive
+(<command>katie</command> refuses to install new packages if they don't have a
+version number greater than the currently available one).
+</para>
+<para>
+You have to make sure that your binary-only NMU doesn't render the package
+uninstallable.  This could happen when a source package generates
+arch-dependent and arch-independent packages that depend on each other via
+$(Source-Version).
+</para>
+<para>
+Despite the required modification of the changelog, these are called
+binary-only NMUs — there is no need in this case to trigger all other
+architectures to consider themselves out of date or requiring recompilation.
+</para>
+<para>
+Such recompilations require special ``magic'' version numbering, so that the
+archive maintenance tools recognize that, even though there is a new Debian
+version, there is no corresponding source update.  If you get this wrong, the
+archive maintainers will reject your upload (due to lack of corresponding
+source code).
+</para>
+<para>
+The ``magic'' for a recompilation-only NMU is triggered by using a suffix
+appended to the package version number, following the form b&lt;number&gt;.
+For instance, if the latest version you are recompiling against was version
+``2.9-3'', your NMU should carry a version of ``2.9-3+b1''.  If the latest
+version was ``3.4+b1'' (i.e, a native package with a previous recompilation
+NMU), your NMU should have a version number of ``3.4+b2''.  <footnote><para> In
+the past, such NMUs used the third-level number on the Debian part of the
+revision to denote their recompilation-only status; however, this syntax was
+ambiguous with native packages and did not allow proper ordering of
+recompile-only NMUs, source NMUs, and security NMUs on the same package, and
+has therefore been abandoned in favor of this new syntax.  </para> </footnote>
+</para>
+<para>
+Similar to initial porter uploads, the correct way of invoking
+<command>dpkg-buildpackage</command> is <literal>dpkg-buildpackage -B</literal>
+to only build the architecture-dependent parts of the package.
+</para>
+</section>
+
+<section id="source-nmu-when-porter">
+<title>When to do a source NMU if you are a porter</title>
+<para>
+Porters doing a source NMU generally follow the guidelines found in <xref
+linkend="nmu"/> , just like non-porters.  However, it is expected that the wait
+cycle for a porter's source NMU is smaller than for a non-porter, since porters
+have to cope with a large quantity of packages.  Again, the situation varies
+depending on the distribution they are uploading to.  It also varies whether
+the architecture is a candidate for inclusion into the next stable release; the
+release managers decide and announce which architectures are candidates.
+</para>
+<para>
+If you are a porter doing an NMU for `unstable', the above guidelines for
+porting should be followed, with two variations.  Firstly, the acceptable
+waiting period — the time between when the bug is submitted to the BTS and
+when it is OK to do an NMU — is seven days for porters working on the
+unstable distribution.  This period can be shortened if the problem is critical
+and imposes hardship on the porting effort, at the discretion of the porter
+group.  (Remember, none of this is Policy, just mutually agreed upon
+guidelines.) For uploads to stable or testing, please coordinate with the
+appropriate release team first.
+</para>
+<para>
+Secondly, porters doing source NMUs should make sure that the bug they submit
+to the BTS should be of severity `serious' or greater.  This ensures that a
+single source package can be used to compile every supported Debian
+architecture by release time.  It is very important that we have one version of
+the binary and source package for all architecture in order to comply with many
+licenses.
+</para>
+<para>
+Porters should try to avoid patches which simply kludge around bugs in the
+current version of the compile environment, kernel, or libc.  Sometimes such
+kludges can't be helped.  If you have to kludge around compiler bugs and the
+like, make sure you <literal>#ifdef</literal> your work properly; also,
+document your kludge so that people know to remove it once the external
+problems have been fixed.
+</para>
+<para>
+Porters may also have an unofficial location where they can put the results of
+their work during the waiting period.  This helps others running the port have
+the benefit of the porter's work, even during the waiting period.  Of course,
+such locations have no official blessing or status, so buyer beware.
+</para>
+</section>
+
+</section>
+
+<section id="porter-automation">
+<title>Porting infrastructure and automation</title>
+<para>
+There is infrastructure and several tools to help automate package porting.
+This section contains a brief overview of this automation and porting to these
+tools; see the package documentation or references for full information.
+</para>
+<section id="s5.10.3.1">
+<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>.
+</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
+lists are used to coordinate porters, and to connect the users of a given port
+with the porters.
+</para>
+</section>
+
+<section id="s5.10.3.2">
+<title>Porter tools</title>
+<para>
+Descriptions of several porting tools can be found in <xref
+linkend="tools-porting"/> .
+</para>
+</section>
+
+<section id="buildd">
+<title><systemitem role="package">buildd</systemitem></title>
+<para>
+The <systemitem role="package">buildd</systemitem> system is used as a
+distributed, client-server build distribution system.  It is usually used in
+conjunction with <emphasis>auto-builders</emphasis>, which are ``slave'' hosts
+which simply check out and attempt to auto-build packages which need to be
+ported.  There is also an email interface to the system, which allows porters
+to ``check out'' a source package (usually one which cannot yet be auto-built)
+and work on it.
+</para>
+<para>
+<systemitem role="package">buildd</systemitem> is not yet available as a
+package; however, most porting efforts are either using it currently or
+planning to use it in the near future.  The actual automated builder is
+packaged as <systemitem role="package">sbuild</systemitem>, see its description
+in <xref linkend="sbuild"/> .  The complete <systemitem
+role="package">buildd</systemitem> system also collects a number of as yet
+unpackaged components which are currently very useful and in use continually,
+such as <command>andrea</command> and <command>wanna-build</command>.
+</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
+information from <command>andrea</command> (source dependencies) and
+<systemitem role="package">quinn-diff</systemitem> (packages needing
+recompilation).
+</para>
+<para>
+We are quite proud of this system, since it has so many possible uses.
+Independent development groups can use the system for different sub-flavors of
+Debian, which may or may not really be of general interest (for instance, a
+flavor of Debian built with <command>gcc</command> bounds checking).  It will
+also enable Debian to recompile entire distributions quickly.
+</para>
+<para>
+The buildds admins of each arch can be contacted at the mail address
+$arch@buildd.debian.org.
+</para>
+</section>
+
+</section>
+
+<section id="packages-arch-specific">
+<title>When your package is <emphasis>not</emphasis> portable</title>
+<para>
+Some packages still have issues with building and/or working on some of the
+architectures supported by Debian, and cannot be ported at all, or not within a
+reasonable amount of time.  An example is a package that is SVGA-specific (only
+i386), or uses other hardware-specific features not supported on all
+architectures.
+</para>
+<para>
+In order to prevent broken packages from being uploaded to the archive, and
+wasting buildd time, you need to do a few things:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+First, make sure your package <emphasis>does</emphasis> fail to build on
+architectures that it cannot support.  There are a few ways to achieve this.
+The preferred way is to have a small testsuite during build time that will test
+the functionality, and fail if it doesn't work.  This is a good idea anyway, as
+this will prevent (some) broken uploads on all architectures, and also will
+allow the package to build as soon as the required functionality is available.
+</para>
+<para>
+Additionally, if you believe the list of supported architectures is pretty
+constant, you should change 'any' to a list of supported architectures in
+debian/control.  This way, the build will fail also, and indicate this to a
+human reader without actually trying.
+</para>
+</listitem>
+<listitem>
+<para>
+In order to prevent autobuilders from needlessly trying to build your package,
+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>;
+please see the top of the file for whom to contact for changes.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Please note that it is insufficient to only add your package to
+Packages-arch-specific without making it fail to build on unsupported
+architectures: A porter or any other person trying to build your package might
+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>
+</para>
+</section>
+
+</section>
+
+<section id="nmu">
+<title>Non-Maintainer Uploads (NMUs)</title>
+<para>
+Under certain circumstances it is necessary for someone other than the official
+package maintainer to make a release of a package.  This is called a
+non-maintainer upload, or NMU.
+</para>
+<para>
+This section handles only source NMUs, i.e.  NMUs which upload a new version of
+the package.  For binary-only NMUs by porters or QA members, please see <xref
+linkend="binary-only-nmu"/> .  If a buildd builds and uploads a package, that
+too is strictly speaking a binary NMU.  See <xref linkend="buildd"/> for some
+more information.
+</para>
+<para>
+The main reason why NMUs are done is when a developer needs to fix another
+developer's package in order to address serious problems or crippling bugs or
+when the package maintainer is unable to release a fix in a timely fashion.
+</para>
+<para>
+First and foremost, it is critical that NMU patches to source should be as
+non-disruptive as possible.  Do not do housekeeping tasks, do not change the
+name of modules or files, do not move directories; in general, do not fix
+things which are not broken.  Keep the patch as small as possible.  If things
+bother you aesthetically, talk to the Debian maintainer, talk to the upstream
+maintainer, or submit a bug.  However, aesthetic changes must
+<emphasis>not</emphasis> be made in a non-maintainer upload.
+</para>
+<para>
+And please remember the Hippocratic Oath: Above all, do no harm.  It is better
+to leave a package with an open grave bug than applying a non-functional patch,
+or one that hides the bug instead of resolving it.
+</para>
+<section id="nmu-guidelines">
+<title>How to do a NMU</title>
+<para>
+NMUs which fix important, serious or higher severity bugs are encouraged and
+accepted.  You should endeavor to reach the current maintainer of the package;
+they might be just about to upload a fix for the problem, or have a better
+solution.
+</para>
+<para>
+NMUs should be made to assist a package's maintainer in resolving bugs.
+Maintainers should be thankful for that help, and NMUers should respect the
+decisions of maintainers, and try to personally help the maintainer by their
+work.
+</para>
+<para>
+A NMU should follow all conventions, written down in this section.  For an
+upload to testing or unstable, this order of steps is recommended:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Make sure that the package's bugs that the NMU is meant to address are all
+filed in the Debian Bug Tracking System (BTS).  If they are not, submit them
+immediately.
+</para>
+</listitem>
+<listitem>
+<para>
+Wait a few days for the response from the maintainer.  If you don't get any
+response, you may want to help them by sending the patch that fixes the bug.
+Don't forget to tag the bug with the patch keyword.
+</para>
+</listitem>
+<listitem>
+<para>
+Wait a few more days.  If you still haven't got an answer from the maintainer,
+send them a mail announcing your intent to NMU the package.  Prepare an NMU as
+described in this section, and test it carefully on your machine (cf.  <xref
+linkend="sanitycheck"/> ).  Double check that your patch doesn't have any
+unexpected side effects.  Make sure your patch is as small and as
+non-disruptive as it can be.
+</para>
+</listitem>
+<listitem>
+<para>
+Upload your package to incoming in <filename>DELAYED/7-day</filename> (cf.
+<xref linkend="delayed-incoming"/> ), send the final patch to the maintainer
+via the BTS, and explain to them that they have 7 days to react if they want to
+cancel the NMU.
+</para>
+</listitem>
+<listitem>
+<para>
+Follow what happens, you're responsible for any bug that you introduced with
+your NMU.  You should probably use <xref linkend="pkg-tracking-system"/> (PTS)
+to stay informed of the state of the package after your NMU.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+At times, the release manager or an organized group of developers can announce
+a certain period of time in which the NMU rules are relaxed.  This usually
+involves shortening the period during which one is to wait before uploading the
+fixes, and shortening the DELAYED period.  It is important to notice that even
+in these so-called bug squashing party times, the NMU'er has to file bugs and
+contact the developer first, and act later.  Please see <xref
+linkend="qa-bsp"/> for details.
+</para>
+<para>
+For the testing distribution, the rules may be changed by the release managers.
+Please take additional care, and acknowledge that the usual way for a package
+to enter testing is through unstable.
+</para>
+<para>
+For the stable distribution, please take extra care.  Of course, the release
+managers may also change the rules here.  Please verify before you upload that
+all your changes are OK for inclusion into the next stable release by the
+release manager.
+</para>
+<para>
+When a security bug is detected, the security team may do an NMU, using their
+own rules.  Please refer to <xref linkend="bug-security"/> for more
+information.
+</para>
+<para>
+For the differences for Porters NMUs, please see <xref
+linkend="source-nmu-when-porter"/> .
+</para>
+<para>
+Of course, it is always possible to agree on special rules with a maintainer
+(like the maintainer asking please upload this fix directly for me, and no diff
+required).
+</para>
+</section>
+
+<section id="nmu-version">
+<title>NMU version numbering</title>
+<para>
+Whenever you have made a change to a package, no matter how trivial, the
+version number needs to change.  This enables our packing system to function.
+</para>
+<para>
+If you are doing a non-maintainer upload (NMU), you should add a new minor
+version number to the <replaceable>debian-revision</replaceable> part of the
+version number (the portion after the last hyphen).  This extra minor number
+will start at `1'.  For example, consider the package `foo', which is at
+version 1.1-3.  In the archive, the source package control file would be
+<filename>foo_1.1-3.dsc</filename>.  The upstream version is `1.1' and the
+Debian revision is `3'.  The next NMU would add a new minor number `.1' to the
+Debian revision; the new source control file would be
+<filename>foo_1.1-3.1.dsc</filename>.
+</para>
+<para>
+The Debian revision minor number is needed to avoid stealing one of the package
+maintainer's version numbers, which might disrupt their work.  It also has the
+benefit of making it visually clear that a package in the archive was not made
+by the official maintainer.
+</para>
+<para>
+If there is no <replaceable>debian-revision</replaceable> component in the
+version number then one should be created, starting at `0.1' (but in case of a
+debian native package still upload it as native package).  If it is absolutely
+necessary for someone other than the usual maintainer to make a release based
+on a new upstream version then the person making the release should start with
+the <replaceable>debian-revision</replaceable> value `0.1'.  The usual
+maintainer of a package should start their
+<replaceable>debian-revision</replaceable> numbering at `1'.
+</para>
+<para>
+If you upload a package to testing or stable, sometimes, you need to fork the
+version number tree.  For this, version numbers like 1.1-3sarge0.1 could be
+used.
+</para>
+</section>
+
+<section id="nmu-changelog">
+<title>Source NMUs must have a new changelog entry</title>
+<para>
+Anyone who is doing a source NMU must create a changelog entry, describing
+which bugs are fixed by the NMU, and generally why the NMU was required and
+what it fixed.  The changelog entry will have the email address of the person
+who uploaded it in the log entry and the NMU version number in it.
+</para>
+<para>
+By convention, source NMU changelog entries start with the line
+</para>
+<screen>
+  * Non-maintainer upload
+</screen>
+</section>
+
+<section id="nmu-patch">
+<title>Source NMUs and the Bug Tracking System</title>
+<para>
+Maintainers other than the official package maintainer should make as few
+changes to the package as possible, and they should always send a patch as a
+unified context diff (<literal>diff -u</literal>) detailing their changes to
+the Bug Tracking System.
+</para>
+<para>
+What if you are simply recompiling the package?  If you just need to recompile
+it for a single architecture, then you may do a binary-only NMU as described in
+<xref linkend="binary-only-nmu"/> which doesn't require any patch to be sent.
+If you want the package to be recompiled for all architectures, then you do a
+source NMU as usual and you will have to send a patch.
+</para>
+<para>
+Bugs fixed by source NMUs used to be tagged fixed instead of closed, but since
+version tracking is in place, such bugs are now also closed with the NMU
+version.
+</para>
+<para>
+Also, after doing an NMU, you have to send the information to the existing bugs
+that are fixed by your NMU, including the unified diff.  Historically, it was
+custom to open a new bug and include a patch showing all the changes you have
+made.  The normal maintainer will either apply the patch or employ an alternate
+method of fixing the problem.  Sometimes bugs are fixed independently upstream,
+which is another good reason to back out an NMU's patch.  If the maintainer
+decides not to apply the NMU's patch but to release a new version, the
+maintainer needs to ensure that the new upstream version really fixes each
+problem that was fixed in the non-maintainer release.
+</para>
+<para>
+In addition, the normal maintainer should <emphasis>always</emphasis> retain
+the entry in the changelog file documenting the non-maintainer upload -- and of
+course, also keep the changes.  If you revert some of the changes, please
+reopen the relevant bug reports.
+</para>
+</section>
+
+<section id="nmu-build">
+<title>Building source NMUs</title>
+<para>
+Source NMU packages are built normally.  Pick a distribution using the same
+rules as found in <xref linkend="distribution"/> , follow the other
+instructions in <xref linkend="upload"/> .
+</para>
+<para>
+Make sure you do <emphasis>not</emphasis> change the value of the maintainer in
+the <filename>debian/control</filename> file.  Your name as given in the NMU
+entry of the <filename>debian/changelog</filename> file will be used for
+signing the changes file.
+</para>
+</section>
+
+<section id="ack-nmu">
+<title>Acknowledging an NMU</title>
+<para>
+If one of your packages has been NMU'ed, you have to incorporate the changes in
+your copy of the sources.  This is easy, you just have to apply the patch that
+has been sent to you.  Once this is done, you have to close the bugs that have
+been tagged fixed by the NMU.  The easiest way is to use the
+<literal>-v</literal> option of <command>dpkg-buildpackage</command>, as this
+allows you to include just all changes since your last maintainer upload.
+Alternatively, you can close them manually by sending the required mails to the
+BTS or by adding the required <literal>closes: #nnnn</literal> in the changelog
+entry of your next upload.
+</para>
+<para>
+In any case, you should not be upset by the NMU.  An NMU is not a personal
+attack against the maintainer.  It is a proof that someone cares enough about
+the package that they were willing to help you in your work, so you should be
+thankful.  You may also want to ask them if they would be interested in helping
+you on a more frequent basis as co-maintainer or backup maintainer (see <xref
+linkend="collaborative-maint"/> ).
+</para>
+</section>
+
+<section id="nmu-vs-qa">
+<title>NMU vs QA uploads</title>
+<para>
+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
+improperly orphaned package, please set the maintainer to ``Debian QA Group
+&lt;packages@qa.debian.org&gt;''.
+</para>
+</section>
+
+<section id="nmu-who">
+<title>Who can do an NMU</title>
+<para>
+Only official, registered Debian Developers can do binary or source NMUs.  A
+Debian Developer is someone who has their key in the Debian key ring.
+Non-developers, however, are encouraged to download the source package and
+start hacking on it to fix problems; however, rather than doing an NMU, they
+should just submit worthwhile patches to the Bug Tracking System.  Maintainers
+almost always appreciate quality patches and bug reports.
+</para>
+</section>
+
+<section id="nmu-terms">
+<title>Terminology</title>
+<para>
+There are two new terms used throughout this section: ``binary-only NMU'' and
+``source NMU''.  These terms are used with specific technical meaning
+throughout this document.  Both binary-only and source NMUs are similar, since
+they involve an upload of a package by a developer who is not the official
+maintainer of that package.  That is why it's a
+<emphasis>non-maintainer</emphasis> upload.
+</para>
+<para>
+A source NMU is an upload of a package by a developer who is not the official
+maintainer, for the purposes of fixing a bug in the package.  Source NMUs
+always involves changes to the source (even if it is just a change to
+<filename>debian/changelog</filename>).  This can be either a change to the
+upstream source, or a change to the Debian bits of the source.  Note, however,
+that source NMUs may also include architecture-dependent packages, as well as
+an updated Debian diff.
+</para>
+<para>
+A binary-only NMU is a recompilation and upload of a binary package for a given
+architecture.  As such, it is usually part of a porting effort.  A binary-only
+NMU is a non-maintainer uploaded binary version of a package, with no source
+changes required.  There are many cases where porters must fix problems in the
+source in order to get them to compile for their target architecture; that
+would be considered a source NMU rather than a binary-only NMU.  As you can
+see, we don't distinguish in terminology between porter NMUs and non-porter
+NMUs.
+</para>
+<para>
+Both classes of NMUs, source and binary-only, can be lumped under the term
+``NMU''.  However, this often leads to confusion, since most people think
+``source NMU'' when they think ``NMU''.  So it's best to be careful: always use
+``binary NMU'' or ``binNMU'' for binary-only NMUs.
+</para>
+</section>
+
+</section>
+
+<section id="collaborative-maint">
+<title>Collaborative maintenance</title>
+<para>
+Collaborative maintenance is a term describing the sharing of Debian package
+maintenance duties by several people.  This collaboration is almost always a
+good idea, since it generally results in higher quality and faster bug fix
+turnaround times.  It is strongly recommended that packages with a priority of
+<literal>Standard</literal> or which are part of the base set have
+co-maintainers.
+</para>
+<para>
+Generally there is a primary maintainer and one or more co-maintainers.  The
+primary maintainer is the person whose name is listed in the
+<literal>Maintainer</literal> field of the <filename>debian/control</filename>
+file.  Co-maintainers are all the other maintainers.
+</para>
+<para>
+In its most basic form, the process of adding a new co-maintainer is quite
+easy:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Setup the co-maintainer with access to the sources you build the package from.
+Generally this implies you are using a network-capable version control system,
+such as <command>CVS</command> or <command>Subversion</command>.  Alioth (see
+<xref linkend="alioth"/> ) provides such tools, amongst others.
+</para>
+</listitem>
+<listitem>
+<para>
+Add the co-maintainer's correct maintainer name and address to the
+<literal>Uploaders</literal> field in the global part of the
+<filename>debian/control</filename> file.
+</para>
+<screen>
+: John Buzz &lt;jbuzz@debian.org&gt;, Adam Rex &lt;arex@debian.org&gt;
+</screen>
+</listitem>
+<listitem>
+<para>
+Using the PTS (<xref linkend="pkg-tracking-system"/> ), the co-maintainers
+should subscribe themselves to the appropriate source package.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Another form of collaborative maintenance is team maintenance, which is
+recommended if you maintain several packages with the same group of developers.
+In that case, the Maintainer and Uploaders field of each package must be
+managed with care.  It is recommended to choose between one of the two
+following schemes:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Put the team member mainly responsible for the package in the Maintainer field.
+In the Uploaders, put the mailing list address, and the team members who care
+for the package.
+</para>
+</listitem>
+<listitem>
+<para>
+Put the mailing list address in the Maintainer field.  In the Uploaders field,
+put the team members who care for the package.  In this case, you must make
+sure the mailing list accept bug reports without any human interaction (like
+moderation for non-subscribers).
+</para>
+</listitem>
+</orderedlist>
+<para>
+In any case, it is a bad idea to automatically put all team members in the
+Uploaders field.  It clutters the Developer's Package Overview listing (see
+<xref linkend="ddpo"/> ) with packages one doesn't really care for, and creates
+a false sense of good maintenance.
+</para>
+</section>
+
+<section id="testing">
+<title>The testing distribution</title>
+<section id="testing-basics">
+<title>Basics</title>
+<para>
+Packages are usually installed into the `testing' distribution after they have
+undergone some degree of testing in unstable.
+</para>
+<para>
+They must be in sync on all architectures and mustn't have dependencies that
+make them uninstallable; they also have to have generally no known
+release-critical bugs at the time they're installed into testing.  This way,
+`testing' should always be close to being a release candidate.  Please see
+below for details.
+</para>
+</section>
+
+<section id="testing-unstable">
+<title>Updates from unstable</title>
+<para>
+The scripts that update the <emphasis>testing</emphasis> distribution are run
+each day after the installation of the updated packages; these scripts are
+called <emphasis>britney</emphasis>.  They generate the
+<filename>Packages</filename> files for the <emphasis>testing</emphasis>
+distribution, but they do so in an intelligent manner; they try to avoid any
+inconsistency and to use only non-buggy packages.
+</para>
+<para>
+The inclusion of a package from <emphasis>unstable</emphasis> is conditional on
+the following:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The package must have been available in <emphasis>unstable</emphasis> for 2, 5
+or 10 days, depending on the urgency (high, medium or low).  Please note that
+the urgency is sticky, meaning that the highest urgency uploaded since the
+previous testing transition is taken into account.  Those delays may be doubled
+during a freeze, or testing transitions may be switched off altogether;
+</para>
+</listitem>
+<listitem>
+<para>
+It must have the same number or fewer release-critical bugs than the version
+currently available in <emphasis>testing</emphasis>;
+</para>
+</listitem>
+<listitem>
+<para>
+It must be available on all architectures on which it has previously been built
+in unstable.  <xref linkend="madison"/> may be of interest to check that
+information;
+</para>
+</listitem>
+<listitem>
+<para>
+It must not break any dependency of a package which is already available in
+<emphasis>testing</emphasis>;
+</para>
+</listitem>
+<listitem>
+<para>
+The packages on which it depends must either be available in
+<emphasis>testing</emphasis> or they must be accepted into
+<emphasis>testing</emphasis> at the same time (and they will be if they fulfill
+all the necessary criteria);
+</para>
+</listitem>
+</itemizedlist>
+<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
+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>
+<refentrytitle>crontab</refentrytitle> <manvolnum>5</manvolnum> </citerefentry>
+to keep yourself informed of the progression of your packages into
+<emphasis>testing</emphasis>.
+</para>
+<para>
+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
+more information about the usual problems which may be causing such troubles.
+</para>
+<para>
+Sometimes, some packages never enter <emphasis>testing</emphasis> because the
+set of inter-relationship is too complicated and cannot be sorted out by the
+scripts.  See below for details.
+</para>
+<para>
+Some further dependency analysis is shown on <ulink
+url="http://bjorn.haxx.se/debian/"></ulink> — but be warned, this page also
+shows build dependencies which are not considered by britney.
+</para>
+<section id="outdated">
+<title>out-of-date</title>
+<para>
+For the testing migration script, outdated means: There are different versions
+in unstable for the release architectures (except for the architectures in
+fuckedarches; fuckedarches is a list of architectures that don't keep up (in
+update_out.py), but currently, it's empty).  outdated has nothing whatsoever to
+do with the architectures this package has in testing.
+</para>
+<para>
+Consider this example:
+</para>
+<informaltable pgwide="1">
+<tgroup cols="3">
+<thead>
+<row>
+<entry></entry>
+<entry>alpha</entry>
+<entry>arm</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>testing</entry>
+<entry>1</entry>
+<entry>-</entry>
+</row>
+<row>
+<entry>unstable</entry>
+<entry>1</entry>
+<entry>2</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+The package is out of date on alpha in unstable, and will not go to testing.
+And removing foo from testing would not help at all, the package is still out
+of date on alpha, and will not propagate to testing.
+</para>
+<para>
+However, if ftp-master removes a package in unstable (here on arm):
+</para>
+<informaltable pgwide="1">
+<tgroup cols="4">
+<thead>
+<row>
+<entry></entry>
+<entry>alpha</entry>
+<entry>arm</entry>
+<entry>hurd-i386</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>testing</entry>
+<entry>1</entry>
+<entry>1</entry>
+<entry>-</entry>
+</row>
+<row>
+<entry>unstable</entry>
+<entry>2</entry>
+<entry>-</entry>
+<entry>1</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+In this case, the package is up to date on all release architectures in
+unstable (and the extra hurd-i386 doesn't matter, as it's not a release
+architecture).
+</para>
+<para>
+Sometimes, the question is raised if it is possible to allow packages in that
+are not yet built on all architectures: No.  Just plainly no.  (Except if you
+maintain glibc or so.)
+</para>
+</section>
+
+<section id="removals">
+<title>Removals from testing</title>
+<para>
+Sometimes, a package is removed to allow another package in: This happens only
+to allow <emphasis>another</emphasis> package to go in if it's ready in every
+other sense.  Suppose e.g.  that <emphasis>a</emphasis> cannot be installed
+with the new version of <emphasis>b</emphasis>; then <emphasis>a</emphasis> may
+be removed to allow <emphasis>b</emphasis> in.
+</para>
+<para>
+Of course, there is another reason to remove a package from testing: It's just
+too buggy (and having a single RC-bug is enough to be in this state).
+</para>
+<para>
+Furthermore, if a package has been removed from unstable, and no package in
+testing depends on it any more, then it will automatically be removed.
+</para>
+</section>
+
+<section id="circular">
+<title>circular dependencies</title>
+<para>
+A situation which is not handled very well by britney is if package
+<emphasis>a</emphasis> depends on the new version of package
+<emphasis>b</emphasis>, and vice versa.
+</para>
+<para>
+An example of this is:
+</para>
+<informaltable pgwide="1">
+<tgroup cols="3">
+<thead>
+<row>
+<entry></entry>
+<entry>testing</entry>
+<entry>unstable</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry>a</entry>
+<entry>1; depends: b=1</entry>
+<entry>2; depends: b=2</entry>
+</row>
+<row>
+<entry>b</entry>
+<entry>1; depends: a=1</entry>
+<entry>2; depends: a=2</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+Neither package <emphasis>a</emphasis> nor package <emphasis>b</emphasis> is
+considered for update.
+</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>
+if this happens to one of your packages.
+</para>
+</section>
+
+<section id="s5.13.2.4">
+<title>influence of package in testing</title>
+<para>
+Generally, there is nothing that the status of a package in testing means for
+transition of the next version from unstable to testing, with two exceptions:
+If the RC-bugginess of the package goes down, it may go in even if it is still
+RC-buggy.  The second exception is if the version of the package in testing is
+out of sync on the different arches: Then any arch might just upgrade to the
+version of the source package; however, this can happen only if the package was
+previously forced through, the arch is in fuckedarches, or there was no binary
+package of that arch present in unstable at all during the testing migration.
+</para>
+<para>
+In summary this means: The only influence that a package being in testing has
+on a new version of the same package is that the new version might go in
+easier.
+</para>
+</section>
+
+<section id="details">
+<title>details</title>
+<para>
+If you are interested in details, this is how britney works:
+</para>
+<para>
+The packages are looked at to determine whether they are valid candidates.
+This gives the update excuses.  The most common reasons why a package is not
+considered are too young, RC-bugginess, and out of date on some arches.  For
+this part of britney, the release managers have hammers of various sizes to
+force britney to consider a package.  (Also, the base freeze is coded in that
+part of britney.) (There is a similar thing for binary-only updates, but this
+is not described here.  If you're interested in that, please peruse the code.)
+</para>
+<para>
+Now, the more complex part happens: Britney tries to update testing with the
+valid candidates; first, each package alone, and then larger and even larger
+sets of packages together.  Each try is accepted if testing is not more
+uninstallable after the update than before.  (Before and after this part, some
+hints are processed; but as only release masters can hint, this is probably not
+so important for you.)
+</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
+~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>
+</para>
+<para>
+The hints are available via <ulink
+url="http://ftp-master.debian.org/testing/hints/"></ulink>.
+</para>
+</section>
+
+</section>
+
+<section id="t-p-u">
+<title>Direct updates to testing</title>
+<para>
+The testing distribution is fed with packages from unstable according to the
+rules explained above.  However, in some cases, it is necessary to upload
+packages built only for testing.  For that, you may want to upload to
+<emphasis>testing-proposed-updates</emphasis>.
+</para>
+<para>
+Keep in mind that packages uploaded there are not automatically processed, they
+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>.
+</para>
+<para>
+You should not upload to <emphasis>testing-proposed-updates</emphasis> when you
+can update your packages through <emphasis>unstable</emphasis>.  If you can't
+(for example because you have a newer development version in unstable), you may
+use this facility, but it is recommended that you ask for authorization from
+the release manager first.  Even if a package is frozen, updates through
+unstable are possible, if the upload via unstable does not pull in any new
+dependencies.
+</para>
+<para>
+Version numbers are usually selected by adding the codename of the testing
+distribution and a running number, like 1.2sarge1 for the first upload through
+testing-proposed-updates of package version 1.2.
+</para>
+<para>
+Please make sure you didn't miss any of these items in your upload:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Make sure that your package really needs to go through
+<emphasis>testing-proposed-updates</emphasis>, and can't go through unstable;
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure that you included only the minimal amount of changes;
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure that you included an appropriate explanation in the changelog;
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure that you've written <emphasis>testing</emphasis> or
+<emphasis>testing-proposed-updates</emphasis> into your target distribution;
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure that you've built and tested your package in
+<emphasis>testing</emphasis>, not in <emphasis>unstable</emphasis>;
+</para>
+</listitem>
+<listitem>
+<para>
+Make sure that your version number is higher than the version in
+<emphasis>testing</emphasis> and <emphasis>testing-proposed-updates</emphasis>,
+and lower than in <emphasis>unstable</emphasis>;
+</para>
+</listitem>
+<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
+upload.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="faq">
+<title>Frequently asked questions</title>
+<section id="rc">
+<title>What are release-critical bugs, and how do they get counted?</title>
+<para>
+All bugs of some higher severities are by default considered release-critical;
+currently, these are critical, grave, and serious bugs.
+</para>
+<para>
+Such bugs are presumed to have an impact on the chances that the package will
+be released with the stable release of Debian: in general, if a package has
+open release-critical bugs filed on it, it won't get into testing, and
+consequently won't be released in stable.
+</para>
+<para>
+The unstable bug count are all release-critical bugs without either any
+release-tag (such as potato, woody) or with release-tag sid; also, only if they
+are neither fixed nor set to sarge-ignore.  The testing bug count for a package
+is considered to be roughly the bug count of unstable count at the last point
+when the testing version equalled the unstable version.
+</para>
+<para>
+This will change post-sarge, as soon as we have versions in the bug tracking
+system.
+</para>
+</section>
+
+<section id="s5.13.4.2">
+<title>How could installing a package into testing possibly break other packages?</title>
+<para>
+The structure of the distribution archives is such that they can only contain
+one version of a package; a package is defined by its name.  So when the source
+package acmefoo is installed into testing, along with its binary packages
+acme-foo-bin, acme-bar-bin, libacme-foo1 and libacme-foo-dev, the old version
+is removed.
+</para>
+<para>
+However, the old version may have provided a binary package with an old soname
+of a library, such as libacme-foo0.  Removing the old acmefoo will remove
+libacme-foo0, which will break any packages which depend on it.
+</para>
+<para>
+Evidently, this mainly affects packages which provide changing sets of binary
+packages in different versions (in turn, mainly libraries).  However, it will
+also affect packages upon which versioned dependencies have been declared of
+the ==, &lt;=, or &lt;&lt; varieties.
+</para>
+<para>
+When the set of binary packages provided by a source package change in this
+way, all the packages that depended on the old binaries will have to be updated
+to depend on the new binaries instead.  Because installing such a source
+package into testing breaks all the packages that depended on it in testing,
+some care has to be taken now: all the depending packages must be updated and
+ready to be installed themselves so that they won't be broken, and, once
+everything is ready, manual intervention by the release manager or an assistant
+is normally required.
+</para>
+<para>
+If you are having problems with complicated groups of packages like this,
+contact debian-devel or debian-release for help.
+</para>
+</section>
+
+</section>
+
+</section>
+
+</chapter>
+
diff --git a/po4a/fr/best-pkging-practices.po b/po4a/fr/best-pkging-practices.po
new file mode 100644 (file)
index 0000000..afae0ad
--- /dev/null
@@ -0,0 +1,2506 @@
+# SOME DESCRIPTIVE TITLE
+# Copyright (C) YEAR Free Software Foundation, Inc.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+# 
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"POT-Creation-Date: 2007-06-26 16:13+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: ENCODING"
+
+# type: Content of: <chapter><title>
+#: best-pkging-practices.dbk:5
+msgid "Best Packaging Practices"
+msgstr ""
+
+# type: Content of: <chapter><para>
+#: best-pkging-practices.dbk:7
+msgid ""
+"Debian's quality is largely due to the <ulink "
+"url=\"http://www.debian.org/doc/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 talented people have created great tools, tools which help you, "
+"the Debian maintainer, create and maintain excellent packages."
+msgstr ""
+
+# type: Content of: <chapter><para>
+#: best-pkging-practices.dbk:16
+msgid ""
+"This chapter provides some best practices for Debian developers.  All "
+"recommendations are merely that, and are not requirements or policy.  These "
+"are just some subjective hints, advice and pointers collected from Debian "
+"developers.  Feel free to pick and choose whatever works best for you."
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:22
+msgid "Best practices for <filename>debian/rules</filename>"
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:24
+msgid ""
+"The following recommendations apply to the <filename>debian/rules</filename> "
+"file.  Since <filename>debian/rules</filename> controls the build process "
+"and selects the files which go into the package (directly or indirectly), "
+"it's usually the file maintainers spend the most time on."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:30
+msgid "Helper scripts"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:32
+msgid ""
+"The rationale for using helper scripts in <filename>debian/rules</filename> "
+"is that they let maintainers use and share common logic among many "
+"packages.  Take for instance the question of installing menu entries: you "
+"need to put the file into <filename>/usr/lib/menu</filename> (or "
+"<filename>/usr/lib/menu</filename> for executable binary menufiles, if this "
+"is needed), and add commands to the maintainer scripts to register and "
+"unregister the menu entries.  Since this is a very common thing for packages "
+"to do, why should each maintainer rewrite all this on their own, sometimes "
+"with bugs? Also, supposing the menu directory changed, every package would "
+"have to be changed."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:43
+msgid ""
+"Helper scripts take care of these issues.  Assuming you comply with the "
+"conventions expected by the helper script, the helper takes care of all the "
+"details.  Changes in policy can be made in the helper script; then packages "
+"just need to be rebuilt with the new version of the helper and no other "
+"changes."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:50
+msgid ""
+"<xref linkend=\"tools\"/> contains a couple of different helpers.  The most "
+"common and best (in our opinion) helper system is <systemitem "
+"role=\"package\">debhelper</systemitem>.  Previous helper systems, such as "
+"<systemitem role=\"package\">debmake</systemitem>, were monolithic: you "
+"couldn't pick and choose which part of the helper you found useful, but had "
+"to use the helper to do everything.  <systemitem "
+"role=\"package\">debhelper</systemitem>, however, is a number of separate "
+"little <command>dh_*</command> programs.  For instance, "
+"<command>dh_installman</command> installs and compresses man pages, "
+"<command>dh_installmenu</command> installs menu files, and so on.  Thus, it "
+"offers enough flexibility to be able to use the little helper scripts, where "
+"useful, in conjunction with hand-crafted commands in "
+"<filename>debian/rules</filename>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:64
+msgid ""
+"You can get started with <systemitem role=\"package\">debhelper</systemitem> "
+"by reading <citerefentry> <refentrytitle>debhelper</refentrytitle> "
+"<manvolnum>1</manvolnum> </citerefentry>, and looking at the examples that "
+"come with the package.  <command>dh_make</command>, from the <systemitem "
+"role=\"package\">dh-make</systemitem> package (see <xref "
+"linkend=\"dh-make\"/> ), can be used to convert a vanilla source package to "
+"a <systemitem role=\"package\">debhelper</systemitem>ized package.  This "
+"shortcut, though, should not convince you that you do not need to bother "
+"understanding the individual <command>dh_*</command> helpers.  If you are "
+"going to use a helper, you do need to take the time to learn to use that "
+"helper, to learn its expectations and behavior."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:77
+msgid ""
+"Some people feel that vanilla <filename>debian/rules</filename> files are "
+"better, since you don't have to learn the intricacies of any helper system.  "
+"This decision is completely up to you.  Use what works for you.  Many "
+"examples of vanilla <filename>debian/rules</filename> files are available at "
+"<ulink url=\"http://arch.debian.org/arch/private/srivasta/\"></ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:86
+msgid "Separating your patches into multiple files"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:88
+msgid ""
+"Big, complex packages may have many bugs that you need to deal with.  If you "
+"correct a number of bugs directly in the source, and you're not careful, it "
+"can get hard to differentiate the various patches that you applied.  It can "
+"get quite messy when you have to update the package to a new upstream "
+"version which integrates some of the fixes (but not all).  You can't take "
+"the total set of diffs (e.g., from <filename>.diff.gz</filename>) and work "
+"out which patch sets to back out as a unit as bugs are fixed upstream."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:97
+msgid ""
+"Unfortunately, the packaging system as such currently doesn't provide for "
+"separating the patches into several files.  Nevertheless, there are ways to "
+"separate patches: the patch files are shipped within the Debian patch file "
+"(<filename>.diff.gz</filename>), usually within the "
+"<filename>debian/</filename> directory.  The only difference is that they "
+"aren't applied immediately by dpkg-source, but by the "
+"<literal>build</literal> rule of <filename>debian/rules</filename>.  "
+"Conversely, they are reverted in the <literal>clean</literal> rule."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:107
+msgid ""
+"<command>dbs</command> is one of the more popular approaches to this.  It "
+"does all of the above, and provides a facility for creating new and updating "
+"old patches.  See the package <systemitem role=\"package\">dbs</systemitem> "
+"for more information and <systemitem role=\"package\">hello-dbs</systemitem> "
+"for an example."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:114
+msgid ""
+"<command>dpatch</command> also provides these facilities, but it's intended "
+"to be even easier to use.  See the package <systemitem "
+"role=\"package\">dpatch</systemitem> for documentation and examples (in "
+"<filename>/usr/share/doc/dpatch</filename>)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:122
+msgid "Multiple binary packages"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:124
+msgid ""
+"A single source package will often build several binary packages, either to "
+"provide several flavors of the same software (e.g., the <systemitem "
+"role=\"package\">vim</systemitem> source package) or to make several small "
+"packages instead of a big one (e.g., so the user can install only the subset "
+"needed, and thus save some disk space)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:131
+msgid ""
+"The second case can be easily managed in <filename>debian/rules</filename>.  "
+"You just need to move the appropriate files from the build directory into "
+"the package's temporary trees.  You can do this using "
+"<command>install</command> or <command>dh_install</command> from <systemitem "
+"role=\"package\">debhelper</systemitem>.  Be sure to check the different "
+"permutations of the various packages, ensuring that you have the "
+"inter-package dependencies set right in <filename>debian/control</filename>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:140
+msgid ""
+"The first case is a bit more difficult since it involves multiple recompiles "
+"of the same software but with different configuration options.  The "
+"<systemitem role=\"package\">vim</systemitem> source package is an example "
+"of how to manage this using an hand-crafted "
+"<filename>debian/rules</filename> file."
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:150
+msgid "Best practices for <filename>debian/control</filename>"
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:152
+msgid ""
+"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 "
+"on package descriptions</ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:158
+msgid ""
+"The description of the package, as defined by the corresponding field in the "
+"<filename>control</filename> file, contains both the package synopsis and "
+"the long description for the package.  <xref linkend=\"bpp-desc-basics\"/> "
+"describes common guidelines for both parts of the package description.  "
+"Following that, <xref linkend=\"bpp-pkg-synopsis\"/> provides guidelines "
+"specific to the synopsis, and <xref linkend=\"bpp-pkg-desc\"/> contains "
+"guidelines specific to the description."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:167
+msgid "General guidelines for package descriptions"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:169
+msgid ""
+"The package description should be written for the average likely user, the "
+"average person who will use and benefit from the package.  For instance, "
+"development packages are for developers, and can be technical in their "
+"language.  More general-purpose applications, such as editors, should be "
+"written for a less technical user."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:176
+msgid ""
+"Our review of package descriptions lead us to conclude that most package "
+"descriptions are technical, that is, are not written to make sense for "
+"non-technical users.  Unless your package really is only for technical "
+"users, this is a problem."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:182
+msgid ""
+"How do you write for non-technical users? Avoid jargon.  Avoid referring to "
+"other applications or frameworks that the user might not be familiar with — "
+"GNOME or KDE is fine, since users are probably familiar with these terms, "
+"but GTK+ is probably not.  Try not to assume any knowledge at all.  If you "
+"must use technical terms, introduce them."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:189
+msgid ""
+"Be objective.  Package descriptions are not the place for advocating your "
+"package, no matter how much you love it.  Remember that the reader may not "
+"care about the same things you care about."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:194
+msgid ""
+"References to the names of any other software packages, protocol names, "
+"standards, or specifications should use their canonical forms, if one "
+"exists.  For example, use X Window System, X11, or X; not X Windows, "
+"X-Windows, or X Window.  Use GTK+, not GTK or gtk.  Use GNOME, not Gnome.  "
+"Use PostScript, not Postscript or postscript."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:201
+msgid ""
+"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 "
+"feedback."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:208
+msgid "The package synopsis, or short description"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:210
+msgid ""
+"The synopsis line (the short description) should be concise.  It must not "
+"repeat the package's name (this is policy)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:214
+msgid ""
+"It's a good idea to think of the synopsis as an appositive clause, not a "
+"full sentence.  An appositive clause is defined in WordNet as a grammatical "
+"relation between a word and a noun phrase that follows, e.g., Rudolph the "
+"red-nosed reindeer.  The appositive clause here is red-nosed reindeer.  "
+"Since the synopsis is a clause, rather than a full sentence, we recommend "
+"that it neither start with a capital nor end with a full stop (period).  It "
+"should also not begin with an article, either definite (the) or indefinite "
+"(a or an)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:223
+msgid ""
+"It might help to imagine that the synopsis is combined with the package name "
+"in the following way:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:227
+#, no-wrap
+msgid ""
+"<replaceable>package-name</replaceable> is a "
+"<replaceable>synopsis</replaceable>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:230
+msgid "Alternatively, it might make sense to think of it as"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:233
+#, no-wrap
+msgid ""
+"<replaceable>package-name</replaceable> is "
+"<replaceable>synopsis</replaceable>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:236
+msgid "or, if the package name itself is a plural (such as developers-tools)"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:239
+#, no-wrap
+msgid ""
+"<replaceable>package-name</replaceable> are "
+"<replaceable>synopsis</replaceable>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:242
+msgid ""
+"This way of forming a sentence from the package name and synopsis should be "
+"considered as a heuristic and not a strict rule.  There are some cases where "
+"it doesn't make sense to try to form a sentence."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:249
+msgid "The long description"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:251
+msgid ""
+"The long description is the primary information available to the user about "
+"a package before they install it.  It should provide all the information "
+"needed to let the user decide whether to install the package.  Assume that "
+"the user has already read the package synopsis."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:257
+msgid "The long description should consist of full and complete sentences."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:260
+msgid ""
+"The first paragraph of the long description should answer the following "
+"questions: what does the package do? what task does it help the user "
+"accomplish? It is important to describe this in a non-technical way, unless "
+"of course the audience for the package is necessarily technical."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:266
+msgid ""
+"The following paragraphs should answer the following questions: Why do I as "
+"a user need this package? What other features does the package have? What "
+"outstanding features and deficiencies are there compared to other packages "
+"(e.g., if you need X, use Y instead)? Is this package related to other "
+"packages in some way that is not handled by the package manager (e.g., this "
+"is the client for the foo server)?"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:274
+msgid ""
+"Be careful to avoid spelling and grammar mistakes.  Ensure that you "
+"spell-check it.  Both <command>ispell</command> and "
+"<command>aspell</command> have special modes for checking "
+"<filename>debian/control</filename> files:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:279
+#, no-wrap
+msgid "-d american -g debian/control"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:282
+#, no-wrap
+msgid "-d en -D -c debian/control"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:285
+msgid ""
+"Users usually expect these questions to be answered in the package "
+"description:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:290
+msgid ""
+"What does the package do? If it is an add-on to another package, then the "
+"short description of the package we are an add-on to should be put in here."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:296
+msgid ""
+"Why should I want this package? This is related to the above, but not the "
+"same (this is a mail user agent; this is cool, fast, interfaces with PGP and "
+"LDAP and IMAP, has features X, Y, and Z)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:303
+msgid ""
+"If this package should not be installed directly, but is pulled in by "
+"another package, this should be mentioned."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:309
+msgid ""
+"If the package is experimental, or there are other reasons it should not be "
+"used, if there are other packages that should be used instead, it should be "
+"here as well."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:316
+msgid ""
+"How is this package different from the competition? Is it a better "
+"implementation? more features? different features? Why should I choose this "
+"package."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:325
+msgid "Upstream home page"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:327
+msgid ""
+"We recommend that you add the URL for the package's home page to the package "
+"description in <filename>debian/control</filename>.  This information should "
+"be added at the end of description, using the following format:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:332
+#, no-wrap
+msgid ""
+".\n"
+"  Homepage: http://some-project.some-place.org/"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:336
+msgid ""
+"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>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:341
+msgid ""
+"If there is no home page for the software, this should naturally be left "
+"out."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:344
+msgid ""
+"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 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."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:355
+msgid "Version Control System location"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:357
+msgid ""
+"There are additional fields for the location of the Version Control System "
+"in <filename>debian/control</filename>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:361
+msgid "XS-Vcs-Browser"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:363
+msgid ""
+"Value of this field should be a <literal>http://</literal> URL pointing to a "
+"web-browsable copy of the Version Control System repository used to maintain "
+"the given package, if available."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:368
+msgid ""
+"The information is meant to be useful for the final user, willing to browse "
+"the latest work done on the package (e.g.  when looking for the patch fixing "
+"a bug tagged as <literal>pending</literal> in the bug tracking system)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:375
+msgid "XS-Vcs-*"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:377
+msgid ""
+"Value of this field should be a string identifying unequivocally the "
+"location of the Version Control System repository used to maintain the given "
+"package, if available.  <literal>*</literal> identify the Version Control "
+"System; currently the following systems are supported by the package "
+"tracking system: <literal>arch</literal>, <literal>bzr</literal> (Bazaar), "
+"<literal>cvs</literal>, <literal>darcs</literal>, <literal>git</literal>, "
+"<literal>hg</literal> (Mercurial), <literal>mtn</literal> (Monotone), "
+"<literal>svn</literal> (Subversion).  It is allowed to specify different VCS "
+"fields for the same package: they will all be shown in the PTS web "
+"interface."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:388
+msgid ""
+"The information is meant to be useful for a user knowledgeable in the given "
+"Version Control System and willing to build the current version of a package "
+"from the VCS sources.  Other uses of this information might include "
+"automatic building of the latest VCS version of the given package.  To this "
+"end the location pointed to by the field should better be version agnostic "
+"and point to the main branch (for VCSs supporting such a concept).  Also, "
+"the location pointed to should be accessible to the final user; fulfilling "
+"this requirement might imply pointing to an anonymous access of the "
+"repository instead of pointing to an SSH-accessible version of the same."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:399
+msgid ""
+"In the following example, an instance of the field for a Subversion "
+"repository of the <systemitem role=\"package\">vim</systemitem> package is "
+"shown.  Note how the URL is in the <literal>svn://</literal> scheme (instead "
+"of <literal>svn+ssh://</literal>) and how it points to the "
+"<filename>trunk/</filename> branch.  The use of the "
+"<literal>XS-Vcs-Browser</literal> field described above is also shown."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><screen>
+#: best-pkging-practices.dbk:407
+#, no-wrap
+msgid ""
+"Source: vim\n"
+"  Section: editors\n"
+"  Priority: optional\n"
+"  &lt;snip&gt;\n"
+"  XS-Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim\n"
+"  XS-Vcs-Browser: http://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim"
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:421
+msgid "Best practices for <filename>debian/changelog</filename>"
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:423
+msgid ""
+"The following practices supplement the <ulink "
+"url=\"http://www.debian.org/doc/debian-policy/ch-docs.html#s-changelogs\">Policy "
+"on changelog files</ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:428
+msgid "Writing useful changelog entries"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:430
+msgid ""
+"The changelog entry for a package revision documents changes in that "
+"revision, and only them.  Concentrate on describing significant and "
+"user-visible changes that were made since the last version."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:435
+msgid ""
+"Focus on <emphasis>what</emphasis> was changed — who, how and when are "
+"usually less important.  Having said that, remember to politely attribute "
+"people who have provided notable help in making the package (e.g., those who "
+"have sent in patches)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:441
+msgid ""
+"There's no need to elaborate the trivial and obvious changes.  You can also "
+"aggregate several changes in one entry.  On the other hand, don't be overly "
+"terse if you have undertaken a major change.  Be especially clear if there "
+"are changes that affect the behaviour of the program.  For further "
+"explanations, use the <filename>README.Debian</filename> file."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:448
+msgid ""
+"Use common English so that the majority of readers can comprehend it.  Avoid "
+"abbreviations, tech-speak and jargon when explaining changes that close "
+"bugs, especially for bugs filed by users that did not strike you as "
+"particularly technically savvy.  Be polite, don't swear."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:454
+msgid ""
+"It is sometimes desirable to prefix changelog entries with the names of the "
+"files that were changed.  However, there's no need to explicitly list each "
+"and every last one of the changed files, especially if the change was small "
+"or repetitive.  You may use wildcards."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:460
+msgid ""
+"When referring to bugs, don't assume anything.  Say what the problem was, "
+"how it was fixed, and append the closes: #nnnnn string.  See <xref "
+"linkend=\"upload-bugfix\"/> for more information."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:467
+msgid "Common misconceptions about changelog entries"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:469
+msgid ""
+"The changelog entries should <emphasis role=\"strong\">not</emphasis> "
+"document generic packaging issues (Hey, if you're looking for foo.conf, it's "
+"in /etc/blah/.), since administrators and users are supposed to be at least "
+"remotely acquainted with how such things are generally arranged on Debian "
+"systems.  Do, however, mention if you change the location of a configuration "
+"file."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:477
+msgid ""
+"The only bugs closed with a changelog entry should be those that are "
+"actually fixed in the same package revision.  Closing unrelated bugs in the "
+"changelog is bad practice.  See <xref linkend=\"upload-bugfix\"/> ."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:482
+msgid ""
+"The changelog entries should <emphasis role=\"strong\">not</emphasis> be "
+"used for random discussion with bug reporters (I don't see segfaults when "
+"starting foo with option bar; send in more info), general statements on "
+"life, the universe and everything (sorry this upload took me so long, but I "
+"caught the flu), or pleas for help (the bug list on this package is huge, "
+"please lend me a hand).  Such things usually won't be noticed by their "
+"target audience, but may annoy people who wish to read information about "
+"actual changes in the package.  See <xref linkend=\"bug-answering\"/> for "
+"more information on how to use the bug tracking system."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:493
+msgid ""
+"It is an old tradition to acknowledge bugs fixed in non-maintainer uploads "
+"in the first changelog entry of the proper maintainer upload.  As we have "
+"version tracking now, it is enough to keep the NMUed changelog entries and "
+"just mention this fact in your own changelog entry."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:501
+msgid "Common errors in changelog entries"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:503
+msgid ""
+"The following examples demonstrate some common errors or examples of bad "
+"style in changelog entries."
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:507
+#, no-wrap
+msgid "* Fixed all outstanding bugs."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:510
+msgid "This doesn't tell readers anything too useful, obviously."
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:513
+#, no-wrap
+msgid "* Applied patch from Jane Random."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:516
+msgid "What was the patch about?"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:519
+#, no-wrap
+msgid "* Late night install target overhaul."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:522
+msgid ""
+"Overhaul which accomplished what? Is the mention of late night supposed to "
+"remind us that we shouldn't trust that code?"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:526
+#, no-wrap
+msgid "* Fix vsync FU w/ ancient CRTs."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:529
+msgid ""
+"Too many acronyms, and it's not overly clear what the, uh, fsckup (oops, a "
+"curse word!) was actually about, or how it was fixed."
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:533
+#, no-wrap
+msgid "* This is not a bug, closes: #nnnnnn."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:536
+msgid ""
+"First of all, there's absolutely no need to upload the package to convey "
+"this information; instead, use the bug tracking system.  Secondly, there's "
+"no explanation as to why the report is not a bug."
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:541
+#, no-wrap
+msgid "* Has been fixed for ages, but I forgot to close; closes: #54321."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:544
+msgid ""
+"If for some reason you didn't mention the bug number in a previous changelog "
+"entry, there's no problem, just close the bug normally in the BTS.  There's "
+"no need to touch the changelog file, presuming the description of the fix is "
+"already in (this applies to the fixes by the upstream authors/maintainers as "
+"well, you don't have to track bugs that they fixed ages ago in your "
+"changelog)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:551
+#, no-wrap
+msgid "* Closes: #12345, #12346, #15432"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:554
+msgid ""
+"Where's the description? If you can't think of a descriptive message, start "
+"by inserting the title of each different bug."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:560
+msgid "Supplementing changelogs with NEWS.Debian files"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:562
+msgid ""
+"Important news about changes in a package can also be put in NEWS.Debian "
+"files.  The news will be displayed by tools like apt-listchanges, before all "
+"the rest of the changelogs.  This is the preferred means to let the user "
+"know about significant changes in a package.  It is better than using "
+"debconf notes since it is less annoying and the user can go back and refer "
+"to the NEWS.Debian file after the install.  And it's better than listing "
+"major changes in README.Debian, since the user can easily miss such notes."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:571
+msgid ""
+"The file format is the same as a debian changelog file, but leave off the "
+"asterisks and describe each news item with a full paragraph when necessary "
+"rather than the more concise summaries that would go in a changelog.  It's a "
+"good idea to run your file through dpkg-parsechangelog to check its "
+"formatting as it will not be automatically checked during build as the "
+"changelog is.  Here is an example of a real NEWS.Debian file:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:579
+#, no-wrap
+msgid ""
+"(3.0pl1-74) unstable; urgency=low\n"
+"\n"
+"    The checksecurity script is no longer included with the cron package:\n"
+"    it now has its own package, checksecurity. If you liked the\n"
+"    functionality provided with that script, please install the new\n"
+"    package.\n"
+"\n"
+" -- Steve Greenland &lt;stevegr@debian.org&gt;  Sat,  6 Sep 2003 17:15:03 "
+"-0500"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:589
+msgid ""
+"The NEWS.Debian file is installed as "
+"/usr/share/doc/&lt;package&gt;/NEWS.Debian.gz.  It is compressed, and always "
+"has that name even in Debian native packages.  If you use debhelper, "
+"dh_installchangelogs will install debian/NEWS files for you."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:595
+msgid ""
+"Unlike changelog files, you need not update NEWS.Debian files with every "
+"release.  Only update them if you have something particularly newsworthy "
+"that user should know about.  If you have no news at all, there's no need to "
+"ship a NEWS.Debian file in your package.  No news is good news!"
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:605
+msgid "Best practices for maintainer scripts"
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:607
+msgid ""
+"Maintainer scripts include the files <filename>debian/postinst</filename>, "
+"<filename>debian/preinst</filename>, <filename>debian/prerm</filename> and "
+"<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>."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:615
+msgid ""
+"Maintainer scripts must be idempotent.  That means that you need to make "
+"sure nothing bad will happen if the script is called twice where it would "
+"usually be called once."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:620
+msgid ""
+"Standard input and output may be redirected (e.g.  into pipes) for logging "
+"purposes, so don't rely on them being a tty."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:624
+msgid ""
+"All prompting or interactive configuration should be kept to a minimum.  "
+"When it is necessary, you should use the <systemitem "
+"role=\"package\">debconf</systemitem> package for the interface.  Remember "
+"that prompting in any case can only be in the <literal>configure</literal> "
+"stage of the <filename>postinst</filename> script."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:631
+msgid ""
+"Keep the maintainer scripts as simple as possible.  We suggest you use pure "
+"POSIX shell scripts.  Remember, if you do need any bash features, the "
+"maintainer script must have a bash shebang line.  POSIX shell or Bash are "
+"preferred to Perl, since they enable <systemitem "
+"role=\"package\">debhelper</systemitem> to easily add bits to the scripts."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:638
+msgid ""
+"If you change your maintainer scripts, be sure to test package removal, "
+"double installation, and purging.  Be sure that a purged package is "
+"completely gone, that is, it must remove any files created, directly or "
+"indirectly, in any maintainer script."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:644
+msgid ""
+"If you need to check for the existence of a command, you should use "
+"something like"
+msgstr ""
+
+# type: Content of: <chapter><section><screen>
+#: best-pkging-practices.dbk:648
+#, no-wrap
+msgid "[ -x /usr/sbin/install-docs ]; then ..."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:651
+msgid ""
+"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:"
+msgstr ""
+
+# type: Content of: <chapter><section><screen>
+#: best-pkging-practices.dbk:655
+#, no-wrap
+msgid ""
+"() {\n"
+"    OLDIFS=$IFS\n"
+"    IFS=:\n"
+"    for p in $PATH; do\n"
+"        if [ -x $p/$* ]; then\n"
+"            IFS=$OLDIFS\n"
+"            return 0\n"
+"        fi\n"
+"    done\n"
+"    IFS=$OLDIFS\n"
+"    return 1\n"
+"}"
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:669
+msgid ""
+"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, and false if not.  This is really the most portable way, since "
+"<literal>command -v</literal>, <command>type</command>, and "
+"<command>which</command> are not POSIX."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:676
+msgid ""
+"While <command>which</command> is an acceptable alternative, since it is "
+"from the required <systemitem role=\"package\">debianutils</systemitem> "
+"package, it's not on the root partition.  That is, it's in "
+"<filename>/usr/bin</filename> rather than <filename>/bin</filename>, so one "
+"can't use it in scripts which are run before the <filename>/usr</filename> "
+"partition is mounted.  Most scripts won't have this problem, though."
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:686
+msgid ""
+"Configuration management with <systemitem "
+"role=\"package\">debconf</systemitem>"
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:688
+msgid ""
+"<systemitem role=\"package\">Debconf</systemitem> is a configuration "
+"management system which can be used by all the various packaging scripts "
+"(<filename>postinst</filename> mainly) to request feedback from the user "
+"concerning how to configure the package.  Direct user interactions must now "
+"be avoided in favor of <systemitem role=\"package\">debconf</systemitem> "
+"interaction.  This will enable non-interactive installations in the future."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:696
+msgid ""
+"Debconf is a great tool but it is often poorly used.  Many common mistakes "
+"are listed in the <citerefentry> "
+"<refentrytitle>debconf-devel</refentrytitle> <manvolnum>7</manvolnum> "
+"</citerefentry> man page.  It is something that you must read if you decide "
+"to use debconf.  Also, we document some best practices here."
+msgstr ""
+
+# type: Content of: <chapter><section><para>
+#: best-pkging-practices.dbk:703
+msgid ""
+"These guidelines include some writing style and typography recommendations, "
+"general considerations about debconf usage as well as more specific "
+"recommendations for some parts of the distribution (the installation system "
+"for instance)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:709
+msgid "Do not abuse debconf"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:711
+msgid ""
+"Since debconf appeared in Debian, it has been widely abused and several "
+"criticisms received by the Debian distribution come from debconf abuse with "
+"the need of answering a wide bunch of questions before getting any little "
+"thing installed."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:717
+msgid ""
+"Keep usage notes to what they belong: the NEWS.Debian, or README.Debian "
+"file.  Only use notes for important notes which may directly affect the "
+"package usability.  Remember that notes will always block the install until "
+"confirmed or bother the user by email."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:723
+msgid ""
+"Carefully choose the questions priorities in maintainer scripts.  See "
+"<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
+"<manvolnum>7</manvolnum> </citerefentry> for details about priorities.  Most "
+"questions should use medium and low priorities."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:731
+msgid "General recommendations for authors and translators"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:733
+msgid "Write correct English"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:735
+msgid ""
+"Most Debian package maintainers are not native English speakers.  So, "
+"writing properly phrased templates may not be easy for them."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:739
+msgid ""
+"Please use (and abuse) <email>debian-l10n-english@lists.debian.org</email> "
+"mailing list.  Have your templates proofread."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:743
+msgid ""
+"Badly written templates give a poor image of your package, of your work...or "
+"even of Debian itself."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:747
+msgid ""
+"Avoid technical jargon as much as possible.  If some terms sound common to "
+"you, they may be impossible to understand for others.  If you cannot avoid "
+"them, try to explain them (use the extended description).  When doing so, "
+"try to balance between verbosity and simplicity."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:755
+msgid "Be kind to translators"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:757
+msgid ""
+"Debconf templates may be translated.  Debconf, along with its sister package "
+"<command>po-debconf</command> offers a simple framework for getting "
+"templates translated by translation teams or even individuals."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:762
+msgid ""
+"Please use gettext-based templates.  Install <systemitem "
+"role=\"package\">po-debconf</systemitem> on your development system and read "
+"its documentation (man po-debconf is a good start)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:767
+msgid ""
+"Avoid changing templates too often.  Changing templates text induces more "
+"work to translators which will get their translation fuzzied.  If you plan "
+"changes to your original templates, please contact translators.  Most active "
+"translators are very responsive and getting their work included along with "
+"your modified templates will save you additional uploads.  If you use "
+"gettext-based templates, the translator's name and e-mail addresses are "
+"mentioned in the po files headers."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:776
+msgid ""
+"The use of the <command>podebconf-report-po</command> from the po-debconf "
+"package is highly recommended to warn translators which have incomplete "
+"translations and request them for updates."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:781
+msgid ""
+"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."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:786
+msgid ""
+"Calls for translations posted to <email>debian-i18n@lists.debian.org</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 avoid duplicate work."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:795
+msgid "Unfuzzy complete translations when correcting typos and spelling"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:797
+msgid ""
+"When the text of a debconf template is corrected and you are <emphasis "
+"role=\"strong\">sure</emphasis> that the change does <emphasis "
+"role=\"strong\">not</emphasis> affect translations, please be kind to "
+"translators and unfuzzy their translations."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:803
+msgid ""
+"If you don't do so, the whole template will not be translated as long as a "
+"translator will send you an update."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:807
+msgid ""
+"To <emphasis role=\"strong\">unfuzzy</emphasis> translations, you can "
+"proceed the following way:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:813
+msgid ""
+"Put all incomplete PO files out of the way.  You can check the completeness "
+"by using (needs the <systemitem role=\"package\">gettext</systemitem> "
+"package installed):"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
+#: best-pkging-practices.dbk:818
+#, no-wrap
+msgid ""
+"i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null\n"
+"--statistics $i; done"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:824
+msgid ""
+"move all files which report either fuzzy strings to a temporary place.  "
+"Files which report no fuzzy strings (only translated and untranslated) will "
+"be kept in place."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:831
+msgid ""
+"now <emphasis role=\"strong\">and now only</emphasis>, modify the template "
+"for the typos and check again that translation are not impacted (typos, "
+"spelling errors, sometimes typographical corrections are usually OK)"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:838
+msgid ""
+"run <command>debconf-updatepo</command>.  This will fuzzy all strings you "
+"modified in translations.  You can see this by running the above again"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:844
+msgid "use the following command:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><screen>
+#: best-pkging-practices.dbk:847
+#, no-wrap
+msgid "i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:852
+msgid ""
+"move back to debian/po the files which showed fuzzy strings in the first "
+"step"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><orderedlist><listitem><para>
+#: best-pkging-practices.dbk:857
+msgid "run <command>debconf-updatepo</command> again"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:864
+msgid "Do not make assumptions about interfaces"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:866
+msgid ""
+"Templates text should not make reference to widgets belonging to some "
+"debconf interfaces.  Sentences like If you answer Yes...  have no meaning "
+"for users of graphical interfaces which use checkboxes for boolean "
+"questions."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:871
+msgid ""
+"String templates should also avoid mentioning the default values in their "
+"description.  First, because this is redundant with the values seen by the "
+"users.  Also, because these default values may be different from the "
+"maintainer choices (for instance, when the debconf database was preseeded)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:877
+msgid ""
+"More generally speaking, try to avoid referring to user actions.  Just give "
+"facts."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:883
+msgid "Do not use first person"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:885
+msgid ""
+"You should avoid the use of first person (I will do this...  or We "
+"recommend...).  The computer is not a person and the Debconf templates do "
+"not speak for the Debian developers.  You should use neutral construction.  "
+"Those of you who already wrote scientific publications, just write your "
+"templates like you would write a scientific paper.  However, try using "
+"action voice if still possible, like Enable this if ...  instead of This can "
+"be enabled if ...."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:895
+msgid "Be gender neutral"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:897
+msgid ""
+"The world is made of men and women.  Please use gender-neutral constructions "
+"in your writing."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:905
+msgid "Templates fields definition"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:907
+msgid ""
+"This part gives some information which is mostly taken from the "
+"<citerefentry> <refentrytitle>debconf-devel</refentrytitle> "
+"<manvolnum>7</manvolnum> </citerefentry> manual page."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:912
+msgid "Type"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:914
+msgid "string:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:916
+msgid "Results in a free-form input field that the user can type any string into."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:921
+msgid "password:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:923
+msgid ""
+"Prompts the user for a password.  Use this with caution; be aware that the "
+"password the user enters will be written to debconf's database.  You should "
+"probably clean that value out of the database as soon as is possible."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:930
+msgid "boolean:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:932
+msgid ""
+"A true/false choice.  Remember: true/false, <emphasis role=\"strong\">not "
+"yes/no</emphasis>..."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:938
+msgid "select:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:940
+msgid ""
+"A choice between one of a number of values.  The choices must be specified "
+"in a field named 'Choices'.  Separate the possible values with commas and "
+"spaces, like this: Choices: yes, no, maybe"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:947
+msgid "multiselect:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:949
+msgid ""
+"Like the select data type, except the user can choose any number of items "
+"from the choices list (or chose none of them)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:955
+msgid "note:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:957
+msgid ""
+"Rather than being a question per se, this datatype indicates a note that can "
+"be displayed to the user.  It should be used only for important notes that "
+"the user really should see, since debconf will go to great pains to make "
+"sure the user sees it; halting the install for them to press a key, and even "
+"mailing the note to them in some cases."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:966
+msgid "text:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:968
+msgid "This type is now considered obsolete: don't use it."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:973
+msgid "error:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:975
+msgid ""
+"This type is designed to handle error messages.  It is mostly similar to the "
+"note type.  Frontends may present it differently (for instance, the dialog "
+"frontend of cdebconf draws a red screen instead of the usual blue one)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><para>
+#: best-pkging-practices.dbk:980
+msgid ""
+"It is recommended to use this type for any message that needs user attention "
+"for a correction of any kind."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:988
+msgid "Description: short and extended description"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:990
+msgid ""
+"Template descriptions have two parts: short and extended.  The short "
+"description is in the Description: line of the template."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:994
+msgid ""
+"The short description should be kept short (50 characters or so) so that it "
+"may be accomodated by most debconf interfaces.  Keeping it short also helps "
+"translators, as usually translations tend to end up being longer than the "
+"original."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1000
+msgid ""
+"The short description should be able to stand on its own.  Some interfaces "
+"do not show the long description by default, or only if the user explicitely "
+"asks for it or even do not show it at all.  Avoid things like What do you "
+"want to do?"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1006
+msgid ""
+"The short description does not necessarily have to be a full sentence.  This "
+"is part of the keep it short and efficient recommendation."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1010
+msgid ""
+"The extended description should not repeat the short description word for "
+"word.  If you can't think up a long description, then first, think some "
+"more.  Post to debian-devel.  Ask for help.  Take a writing class! That "
+"extended description is important.  If after all that you still can't come "
+"up with anything, leave it blank."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1017
+msgid ""
+"The extended description should use complete sentences.  Paragraphs should "
+"be kept short for improved readability.  Do not mix two ideas in the same "
+"paragraph but rather use another paragraph."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1022
+msgid ""
+"Don't be too verbose.  User tend to ignore too long screens.  20 lines are "
+"by experience a border you shouldn't cross, because that means that in the "
+"classical dialog interface, people will need to scroll, and lot of people "
+"just don't do that."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1028
+msgid ""
+"The extended description should <emphasis role=\"strong\">never</emphasis> "
+"include a question."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1032
+msgid ""
+"For specific rules depending on templates type (string, boolean, etc.), "
+"please read below."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1038
+msgid "Choices"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1040
+msgid ""
+"This field should be used for Select and Multiselect types.  It contains the "
+"possible choices which will be presented to users.  These choices should be "
+"separated by commas."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1047
+msgid "Default"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1049
+msgid ""
+"This field is optional.  It contains the default answer for string, select "
+"and multiselect templates.  For multiselect templates, it may contain a "
+"comma-separated list of choices."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1058
+msgid "Templates fields specific style guide"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1060
+msgid "Type field"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1062
+msgid ""
+"No specific indication except: use the appropriate type by referring to the "
+"previous section."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1068
+msgid "Description field"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1070
+msgid ""
+"Below are specific instructions for properly writing the Description (short "
+"and extended) depending on the template type."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1074
+msgid "String/password templates"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1078
+msgid ""
+"The short description is a prompt and <emphasis "
+"role=\"strong\">not</emphasis> a title.  Avoid question style prompts (IP "
+"Address?) in favour of opened prompts (IP address:).  The use of colons is "
+"recommended."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1085
+msgid ""
+"The extended description is a complement to the short description.  In the "
+"extended part, explain what is being asked, rather than ask the same "
+"question again using longer words.  Use complete sentences.  Terse writing "
+"style is strongly discouraged."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1095
+msgid "Boolean templates"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1099
+msgid ""
+"The short description should be phrased in the form of a question which "
+"should be kept short and should generally end with a question mark.  Terse "
+"writing style is permitted and even encouraged if the question is rather "
+"long (remember that translations are often longer than original versions)"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1107
+msgid ""
+"Again, please avoid referring to specific interface widgets.  A common "
+"mistake for such templates is if you answer Yes-type constructions."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1115
+msgid "Select/Multiselect"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1119
+msgid ""
+"The short description is a prompt and <emphasis "
+"role=\"strong\">not</emphasis> a title.  Do <emphasis "
+"role=\"strong\">not</emphasis> use useless Please choose...  constructions.  "
+"Users are clever enough to figure out they have to choose something...:)"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1127
+msgid ""
+"The extended description will complete the short description.  It may refer "
+"to the available choices.  It may also mention that the user may choose more "
+"than one of the available choices, if the template is a multiselect one "
+"(although the interface often makes this clear)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><title>
+#: best-pkging-practices.dbk:1137
+msgid "Notes"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1141
+msgid "The short description should be considered to be a *title*."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1146
+msgid ""
+"The extended description is what will be displayed as a more detailed "
+"explanation of the note.  Phrases, no terse writing style."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1152
+msgid ""
+"<emphasis role=\"strong\">Do not abuse debconf.</emphasis> Notes are the "
+"most common way to abuse debconf.  As written in debconf-devel manual page: "
+"it's best to use them only for warning about very serious problems.  The "
+"NEWS.Debian or README.Debian files are the appropriate location for a lot of "
+"notes.  If, by reading this, you consider converting your Note type "
+"templates to entries in NEWS/Debian or README.Debian, plus consider keeping "
+"existing translations for the future."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1167
+msgid "Choices field"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1169
+msgid ""
+"If the Choices are likely to change often, please consider using the "
+"__Choices trick.  This will split each individual choice into a single "
+"string, which will considerably help translators for doing their work."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1176 best-pkging-practices.dbk:1214
+msgid "Default field"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1178
+msgid ""
+"If the default value, for a select template, is likely to vary depending on "
+"the user language (for instance, if the choice is a language choice), please "
+"use the _DefaultChoice trick."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1183
+msgid ""
+"This special field allow translators to put the most appropriate choice "
+"according to their own language.  It will become the default choice when "
+"their language is used while your own mentioned Default Choice will be used "
+"chan using English."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1189
+msgid "Example, taken from the geneweb package templates:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><screen>
+#: best-pkging-practices.dbk:1192
+#, no-wrap
+msgid ""
+": geneweb/lang\n"
+"Type: select\n"
+"__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)\n"
+"# This is the default choice. Translators may put their own language here\n"
+"# instead of the default.\n"
+"# WARNING : you MUST use the ENGLISH FORM of your language\n"
+"# For instance, the french translator will need to put French (fr) here.\n"
+"_DefaultChoice: English (en)[ translators, please see comment in PO files]\n"
+"_Description: Geneweb default language:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1203
+msgid ""
+"Note the use of brackets which allow internal comments in debconf fields.  "
+"Also note the use of comments which will show up in files the translators "
+"will work with."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1208
+msgid ""
+"The comments are needed as the DefaultChoice trick is a bit confusing: the "
+"translators may put their own choice"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1216
+msgid ""
+"Do NOT use empty default field.  If you don't want to use default values, do "
+"not use Default at all."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1220
+msgid ""
+"If you use po-debconf (and you <emphasis role=\"strong\">should</emphasis>, "
+"see 2.2), consider making this field translatable, if you think it may be "
+"translated."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para>
+#: best-pkging-practices.dbk:1225
+msgid ""
+"If the default value may vary depending on language/country (for instance "
+"the default value for a language choice), consider using the special "
+"_DefaultChoice type documented in <citerefentry> "
+"<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
+"</citerefentry>)."
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:1237
+msgid "Internationalization"
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1239
+msgid "Handling debconf translations"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1241
+msgid ""
+"Like porters, translators have a difficult task.  They work on many packages "
+"and must collaborate with many different maintainers.  Moreover, most of the "
+"time, they are not native English speakers, so you may need to be "
+"particularly patient with them."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1247
+msgid ""
+"The goal of <systemitem role=\"package\">debconf</systemitem> was to make "
+"packages configuration easier for maintainers and for users.  Originally, "
+"translation of debconf templates was handled with "
+"<command>debconf-mergetemplate</command>.  However, that technique is now "
+"deprecated; the best way to accomplish <systemitem "
+"role=\"package\">debconf</systemitem> internationalization is by using the "
+"<systemitem role=\"package\">po-debconf</systemitem> package.  This method "
+"is easier both for maintainer and translators; transition scripts are "
+"provided."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1257
+msgid ""
+"Using <systemitem role=\"package\">po-debconf</systemitem>, the translation "
+"is stored in <filename>po</filename> files (drawing from "
+"<command>gettext</command> translation techniques).  Special template files "
+"contain the original messages and mark which fields are translatable.  When "
+"you change the value of a translatable field, by calling "
+"<command>debconf-updatepo</command>, the translation is marked as needing "
+"attention from the translators.  Then, at build time, the "
+"<command>dh_installdebconf</command> program takes care of all the needed "
+"magic to add the template along with the up-to-date translations into the "
+"binary packages.  Refer to the <citerefentry> "
+"<refentrytitle>po-debconf</refentrytitle> <manvolnum>7</manvolnum> "
+"</citerefentry> manual page for details."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1273
+msgid "Internationalized documentation"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1275
+msgid ""
+"Internationalizing documentation is crucial for users, but a lot of labor.  "
+"There's no way to eliminate all that work, but you can make things easier "
+"for translators."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1280
+msgid ""
+"If you maintain documentation of any size, its easier for translators if "
+"they have access to a source control system.  That lets translators see the "
+"differences between two versions of the documentation, so, for instance, "
+"they 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 "
+"]\\|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 the current revision of the file to be translated "
+"and, for a translated file, the revision of the original file the "
+"translation is based on.  You might wish to adapt and provide that in your "
+"CVS area."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1295
+msgid ""
+"If you maintain XML or SGML documentation, we suggest that you isolate any "
+"language-independent information and define those as entities in a separate "
+"file which is included by all the different translations.  This makes it "
+"much easier, for instance, to keep URLs up to date across multiple files."
+msgstr ""
+
+# type: Content of: <chapter><section><title>
+#: best-pkging-practices.dbk:1305
+msgid "Common packaging situations"
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1307
+msgid "Packages using <command>autoconf</command>/<command>automake</command>"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1309
+msgid ""
+"Keeping <command>autoconf</command>'s <filename>config.sub</filename> and "
+"<filename>config.guess</filename> files up to date is critical for porters, "
+"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 "
+"<systemitem role=\"package\">autotools-dev</systemitem> package.  You're "
+"strongly encouraged to read this file and to follow the given "
+"recommendations."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1321
+msgid "Libraries"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1323
+msgid ""
+"Libraries are always difficult to package for various reasons.  The policy "
+"imposes many constraints to ease their maintenance and to make sure upgrades "
+"are as simple as possible when a new upstream version comes out.  Breakage "
+"in a library can result in dozens of dependent packages breaking."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1329
+msgid ""
+"Good practices for library packaging have been grouped in <ulink "
+"url=\"http://www.netfort.gr.jp/~dancer/column/libpkg-guide/\">the library "
+"packaging guide</ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1336
+msgid "Documentation"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1338
+msgid ""
+"Be sure to follow the <ulink "
+"url=\"http://www.debian.org/doc/debian-policy/ch-docs.html\">Policy on "
+"documentation</ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1343
+msgid ""
+"If your package contains documentation built from XML or SGML, we recommend "
+"you not ship the XML or SGML source in the binary package(s).  If users want "
+"the source of the documentation, they should retrieve the source package."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1348
+msgid ""
+"Policy specifies that documentation should be shipped in HTML format.  We "
+"also recommend shipping documentation in PDF and plain text format if "
+"convenient and if output of reasonable quality is possible.  However, it is "
+"generally not appropriate to ship plain text versions of documentation whose "
+"source format is HTML."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1355
+msgid ""
+"Major shipped manuals should register themselves with <systemitem "
+"role=\"package\">doc-base</systemitem> on installation.  See the <systemitem "
+"role=\"package\">doc-base</systemitem> package documentation for more "
+"information."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1363
+msgid "Specific types of packages"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1365
+msgid ""
+"Several specific types of packages have special sub-policies and "
+"corresponding packaging rules and practices:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1371
+msgid ""
+"Perl related packages have a <ulink "
+"url=\"http://www.debian.org/doc/packaging-manuals/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)."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1380
+msgid ""
+"Python related packages have their python policy; see "
+"<filename>/usr/share/doc/python/python-policy.txt.gz</filename> in the "
+"<systemitem role=\"package\">python</systemitem> package."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1387
+msgid ""
+"Emacs related packages have the <ulink "
+"url=\"http://www.debian.org/doc/packaging-manuals/debian-emacs-policy\">emacs "
+"policy</ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1394
+msgid ""
+"Java related packages have their <ulink "
+"url=\"http://www.debian.org/doc/packaging-manuals/java-policy/\">java "
+"policy</ulink>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1401
+msgid ""
+"Ocaml related packages have their own policy, found in "
+"<filename>/usr/share/doc/ocaml/ocaml_packaging_policy.gz</filename> from the "
+"<systemitem role=\"package\">ocaml</systemitem> package.  A good example is "
+"the <systemitem role=\"package\">camlzip</systemitem> source package."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1409
+msgid ""
+"Packages providing XML or SGML DTDs should conform to the recommendations "
+"found in the <systemitem role=\"package\">sgml-base-doc</systemitem> "
+"package."
+msgstr ""
+
+# type: Content of: <chapter><section><section><itemizedlist><listitem><para>
+#: best-pkging-practices.dbk:1415
+msgid ""
+"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>."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1424
+msgid "Architecture-independent data"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1426
+msgid ""
+"It is not uncommon to have a large amount of architecture-independent data "
+"packaged with a program.  For example, audio files, a collection of icons, "
+"wallpaper patterns, or other graphic files.  If the size of this data is "
+"negligible compared to the size of the rest of the package, it's probably "
+"best to keep it all in a single package."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1433
+msgid ""
+"However, if the size of the data is considerable, consider splitting it out "
+"into a separate, architecture-independent package (_all.deb).  By doing "
+"this, you avoid needless duplication of the same data into eleven or more "
+".debs, one per each architecture.  While this adds some extra overhead into "
+"the <filename>Packages</filename> files, it saves a lot of disk space on "
+"Debian mirrors.  Separating out architecture-independent data also reduces "
+"processing time of <command>lintian</command> or <command>linda</command> "
+"(see <xref linkend=\"tools-lint\"/> ) when run over the entire Debian "
+"archive."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1445
+msgid "Needing a certain locale during build"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1447
+msgid ""
+"If you need a certain locale during build, you can create a temporary file "
+"via this trick:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1451
+msgid ""
+"If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to the "
+"name of the locale you generate, you should get what you want without being "
+"root.  Something like this:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:1456
+#, no-wrap
+msgid ""
+"=debian/tmpdir/usr/lib/locale\n"
+"LOCALE_NAME=en_IN\n"
+"LOCALE_CHARSET=UTF-8\n"
+"\n"
+"mkdir -p $LOCALE_PATH\n"
+"localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET "
+"$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET\n"
+"\n"
+"# Using the locale\n"
+"LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date"
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1469
+msgid "Make transition packages deborphan compliant"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1471
+msgid ""
+"Deborphan is a program for helping users to detect which packages can safely "
+"be removed from the system, i.e.  the ones that have no packages depending "
+"on them.  The default operation is to search only within the libs and "
+"oldlibs sections, to hunt down unused libraries.  But when passed the right "
+"argument, it tries to catch other useless packages."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1478
+msgid ""
+"For example, with --guess-dummy, deborphan tries to search all transitional "
+"packages which were needed for upgrade but which can now safely be removed.  "
+"For that, it looks for the string dummy or transitional in their short "
+"description."
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1484
+msgid ""
+"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:"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:1488
+#, no-wrap
+msgid "-cache search .|grep dummy"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1491
+msgid "or"
+msgstr ""
+
+# type: Content of: <chapter><section><section><screen>
+#: best-pkging-practices.dbk:1494
+#, no-wrap
+msgid "-cache search .|grep transitional"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1497
+msgid "."
+msgstr ""
+
+# type: Content of: <chapter><section><section><title>
+#: best-pkging-practices.dbk:1502
+msgid "Best practices for <filename>orig.tar.gz</filename> files"
+msgstr ""
+
+# type: Content of: <chapter><section><section><para>
+#: best-pkging-practices.dbk:1504
+msgid ""
+"There are two kinds of original source tarballs: Pristine source and "
+"repackaged upstream source."
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><title>
+#: best-pkging-practices.dbk:1508
+msgid "Pristine source"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para><footnote>
+#: best-pkging-practices.dbk:1510
+msgid ""
+"The defining characteristic of a pristine source tarball is that the "
+".orig.tar.gz file is byte-for-byte identical to a tarball officially "
+"distributed by the upstream author.  <footnote>"
+msgstr ""
+
+# type: Content of: <chapter><section><section><section><para><footnote><para>
+#: best-pkging-practices.dbk:1512
+msgid ""
+"We cannot prevent upstream authors from changing the tarball they distribute "
+"without also incrementing the version number, so there can be no guarantee "
+"that a pristine tarball is identical to what upstream "
+"<emphasis>currently</emphasis> distributing at any point in time.  All that "
+"can be expected is that it is identical to something that upstream once "
+"<emphasis>did</emphasis> distribute.  If a difference arises later (say, if "
+"upstream notices that he wasn't using maximal comression in his original "
+"distribution and then re-<literal>gzip</literal>s it), that's just too bad.  "