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>
+into <filename>/usr/share/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
<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.
+Important news about changes in a package can also be put in <filename>
+NEWS.Debian</filename> 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.
+it is less annoying and the user can go back and refer to the <filename>
+NEWS.Debian</filename> file after the install. And it's better than listing
+major changes in <filename>README.Debian</filename>, 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:
+good idea to run your file through <literal>dpkg-parsechangelog</literal> to
+check its formatting as it will not be automatically checked during build as
+the changelog is. Here is an example of a real <filename>NEWS.Debian
+</filename> file:
</para>
<screen>
cron (3.0pl1-74) unstable; urgency=low
-- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
</screen>
<para>
-The NEWS.Debian file is installed as
-/usr/share/doc/<package>/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.
+The <filename>NEWS.Debian</filename> file is installed as <filename>
+/usr/share/doc/<replaceable>package</replaceable>/NEWS.Debian.gz</filename>.
+It is compressed, and always has that name even in Debian native packages.
+If you use <literal>debhelper</literal>, <literal>dh_installchangelogs
+</literal> will install <filename>debian/NEWS</filename> 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!
+Unlike changelog files, you need not update <filename>NEWS.Debian</filename>
+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 <filename>NEWS.Debian</filename> file in your package. No news
+is good news!
</para>
</section>
<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).
+documentation (<literal>man po-debconf</literal> is a good start).
</para>
<para>
Avoid changing templates too often. Changing templates text induces more work
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.
+The use of the <command>podebconf-report-po</command> from the <systemitem
+role="package">po-debconf</systemitem> 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
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 example, with <literal>--guess-dummy</literal>, <command>deborphan</command>
+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>
<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
+<literal>.orig.tar.gz</literal> 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
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
+re-<command>gzip</command>s it), that's just too bad. Since there is no good
+way to upload a new <literal>.orig.tar.gz</literal> 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
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><upstream-version></literal> and
+In these cases the developer must construct a suitable <literal>.orig.tar.gz
+</literal> 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><upstream-version></literal> and
<literal><debian-revision></literal>.
</para>
<para>
if you repackage source that could have been pristine.
</para>
<para>
-A repackaged .orig.tar.gz
+A repackaged <literal>.orig.tar.gz</literal>
</para>
<orderedlist numeration="arabic">
<listitem>
<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.
+The debugging symbols can be extracted from an object file using <command>
+objcopy --only-keep-debug</command>. Then the object file can be stripped,
+and <command>objcopy --add-gnu-debuglink</command> 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.
+The <command>dh_strip</command> command in debhelper supports creating debug
+packages, and can take care of using <command>objcopy</command> to separate
+out the debugging symbols for you. If your package uses debhelper, all you
+need to do is call <command>dh_strip --dbg-package=libfoo-dbg</command>, and
+add an entry to <filename>debian/control</filename> for the debug package.
</para>
<para>
Note that the Debian package should depend on the package that it provides
&email-debian-devel-announce; 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).
+(like a new <command>perl</command> version which requires recompilation of all
+the binary modules).
</para>
<para>
The rules for non-maintainer uploads differ during the parties because the
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 <command>mia-query --help</command>
-to see how to query the database. If you find that no information has been
-recorded about an inactive maintainer yet, or that you can add more
-information, you should generally proceed as follows.
+<filename>/org/qa.debian.org/mia</filename> on the host <literal>qa.debian.org
+</literal>, and can be queried with the <command>mia-query</command> tool.
+Use <command>mia-query --help</command> to see how to query the database.
+If you find that no information has been recorded about an inactive maintainer yet,
+or that you can add more information, you should generally proceed as follows.
</para>
<para>
The first step is to politely contact the maintainer, and wait a reasonable
<itemizedlist>
<listitem>
<para>
-The
echelon information available through the <ulink
+The
<literal>echelon</literal> information available through the <ulink
url="&url-debian-db;">developers' LDAP database</ulink>, which indicates
when the developer last posted to a Debian mailing list. (This includes
-uploads via debian-*-changes lists.) Also, remember to check whether the
-maintainer is marked as on vacation in the database.
+mails about uploads distributed via the &email-debian-devel-changes; list.)
+Also, remember to check whether the maintainer is marked as on vacation in
+the database.
</para>
</listitem>
<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.
+an official Debian developer. The <literal>echelon</literal> 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;,
</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;.
+README file in <filename>/org/qa.debian.org/mia</filename> on <literal>
+qa.debian.org</literal> where the technical details and the MIA procedures are
+documented and contact &email-mia;.
</para>
</section>
<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>.
+posted to &email-debian-devel-changes;.
</para>
</listitem>
<listitem>
<section id="s5.6.5">
<title>Other upload queues</title>
<para>
-The scp queues on <literal>&ftp-master-host;</literal>, and security are mostly
-unusable due to the login restrictions on those hosts.
+The scp queues on <literal>&ftp-master-host;</literal>, and <literal>
+security.debian.org</literal> 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
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.
+<literal>security.debian.org</literal>.
</para>
<!-- information about the security database goes here once it's ready -->
<!-- (mdz) -->
</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>).
+Unless the upstream source has been uploaded to <literal>security.debian.org
+</literal> 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 </literal>security.debian.org</literal> with the same
+upstream version, you may upload without upstream source (<literal>
+dpkg-buildpackage -sd</literal>).
</para>
</listitem>
<listitem>
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
+Do <emphasis role="strong">NOT</emphasis> upload your fix to <literal>
+proposed-updates</literal> without coordinating with the security team.
+Packages from <literal>security.debian.org</literal> will be copied into
+the <literal>proposed-updates</literal> 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
</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
+<literal>security.debian.org</literal> as well as proposed for the proper
<replaceable>distribution</replaceable><literal>-proposed-updates</literal>
on <literal>&ftp-master-host;</literal>.
</para>
</para>
<para>
The buildds admins of each arch can be contacted at the mail address
-$arch@buildd.debian.org.
+<literal><replaceable>arch</replaceable>@buildd.debian.org</literal>.
</para>
</section>
For the <literal>testing</literal> migration script, outdated means: There are
different versions in <literal>unstable</literal> 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 <literal>testing</literal>.
+architectures that don't keep up (in <filename>update_out.py</filename>), but
+currently, it's empty). outdated has nothing whatsoever to do with the
+architectures this package has in <literal>testing</literal>.
</para>
<para>
Consider this example:
</para>
<para>
If you are having problems with complicated groups of packages like this,
-contact debian-devel or debian-release for help.
+contact &email-debian-devel; or &email-debian-release; for help.
</para>
</section>
~ianmdlvl / developers-reference.git / commitdiff