1826 lines
143 KiB
HTML
1826 lines
143 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 5. Managing Packages</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="Debian Developer's Reference" /><link rel="up" href="index.html" title="Debian Developer's Reference" /><link rel="prev" href="resources.html" title="Chapter 4. Resources for Debian Developers" /><link rel="next" href="best-pkging-practices.html" title="Chapter 6. Best Packaging Practices" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Managing Packages</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="resources.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="best-pkging-practices.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 5. Managing Packages"><div class="titlepage"><div><div><h2 class="title"><a id="pkgs"></a>Chapter 5. Managing Packages</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="pkgs.html#newpackage">5.1. New packages</a></span></dt><dt><span class="section"><a href="pkgs.html#changelog-entries">5.2. Recording changes in the package</a></span></dt><dt><span class="section"><a href="pkgs.html#sanitycheck">5.3. Testing the package</a></span></dt><dt><span class="section"><a href="pkgs.html#sourcelayout">5.4. Layout of the source package</a></span></dt><dt><span class="section"><a href="pkgs.html#distribution">5.5. Picking a distribution</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#upload-stable">5.5.1. Special case: uploads to the <code class="literal">stable</code> and
|
||
<code class="literal">oldstable</code> distributions</a></span></dt><dt><span class="section"><a href="pkgs.html#upload-t-p-u">5.5.2. Special case: uploads to <code class="literal">testing/testing-proposed-updates</code></a></span></dt></dl></dd><dt><span class="section"><a href="pkgs.html#upload">5.6. Uploading a package</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#upload-ftp-master">5.6.1. Uploading to <code class="literal">ftp-master</code></a></span></dt><dt><span class="section"><a href="pkgs.html#delayed-incoming">5.6.2. Delayed uploads</a></span></dt><dt><span class="section"><a href="pkgs.html#s5.6.4">5.6.3. Security uploads</a></span></dt><dt><span class="section"><a href="pkgs.html#s5.6.5">5.6.4. Other upload queues</a></span></dt><dt><span class="section"><a href="pkgs.html#upload-notification">5.6.5. Notification that a new package has been installed</a></span></dt></dl></dd><dt><span class="section"><a href="pkgs.html#override-file">5.7. Specifying the package section, subsection and priority</a></span></dt><dt><span class="section"><a href="pkgs.html#bug-handling">5.8. Handling bugs</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#bug-monitoring">5.8.1. Monitoring bugs</a></span></dt><dt><span class="section"><a href="pkgs.html#bug-answering">5.8.2. Responding to bugs</a></span></dt><dt><span class="section"><a href="pkgs.html#bug-housekeeping">5.8.3. Bug housekeeping</a></span></dt><dt><span class="section"><a href="pkgs.html#upload-bugfix">5.8.4. When bugs are closed by new uploads</a></span></dt><dt><span class="section"><a href="pkgs.html#bug-security">5.8.5. Handling security-related bugs</a></span></dt></dl></dd><dt><span class="section"><a href="pkgs.html#archive-manip">5.9. Moving, removing, renaming, adopting, and orphaning packages</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#moving-pkgs">5.9.1. Moving packages</a></span></dt><dt><span class="section"><a href="pkgs.html#removing-pkgs">5.9.2. Removing packages</a></span></dt><dt><span class="section"><a href="pkgs.html#s5.9.3">5.9.3. Replacing or renaming packages</a></span></dt><dt><span class="section"><a href="pkgs.html#orphaning">5.9.4. Orphaning a package</a></span></dt><dt><span class="section"><a href="pkgs.html#adopting">5.9.5. Adopting a package</a></span></dt></dl></dd><dt><span class="section"><a href="pkgs.html#porting">5.10. Porting and being ported</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#kind-to-porters">5.10.1. Being kind to porters</a></span></dt><dt><span class="section"><a href="pkgs.html#porter-guidelines">5.10.2. Guidelines for porter uploads</a></span></dt><dt><span class="section"><a href="pkgs.html#porter-automation">5.10.3. Porting infrastructure and automation</a></span></dt><dt><span class="section"><a href="pkgs.html#packages-arch-specific">5.10.4. When your package is <span class="emphasis"><em>not</em></span> portable</a></span></dt><dt><span class="section"><a href="pkgs.html#non-free-buildd">5.10.5. Marking non-free packages as auto-buildable</a></span></dt></dl></dd><dt><span class="section"><a href="pkgs.html#nmu">5.11. Non-Maintainer Uploads (NMUs)</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#nmu-guidelines">5.11.1. When and how to do an NMU</a></span></dt><dt><span class="section"><a href="pkgs.html#nmu-changelog">5.11.2. NMUs and <code class="filename">debian/changelog</code></a></span></dt><dt><span class="section"><a href="pkgs.html#nmu-delayed">5.11.3. Using the <code class="literal">DELAYED/</code> queue</a></span></dt><dt><span class="section"><a href="pkgs.html#nmu-maintainer">5.11.4. NMUs from the maintainer's point of view</a></span></dt><dt><span class="section"><a href="pkgs.html#nmu-binnmu">5.11.5. Source NMUs vs Binary-only NMUs (binNMUs)</a></span></dt><dt><span class="section"><a href="pkgs.html#nmu-qa-upload">5.11.6. NMUs vs QA uploads</a></span></dt><dt><span class="section"><a href="pkgs.html#nmu-team-upload">5.11.7. NMUs vs team uploads</a></span></dt></dl></dd><dt><span class="section"><a href="pkgs.html#collaborative-maint">5.12. Collaborative maintenance</a></span></dt><dt><span class="section"><a href="pkgs.html#testing">5.13. The testing distribution</a></span></dt><dd><dl><dt><span class="section"><a href="pkgs.html#testing-basics">5.13.1. Basics</a></span></dt><dt><span class="section"><a href="pkgs.html#testing-unstable">5.13.2. Updates from unstable</a></span></dt><dt><span class="section"><a href="pkgs.html#t-p-u">5.13.3. Direct updates to testing</a></span></dt><dt><span class="section"><a href="pkgs.html#faq">5.13.4. Frequently asked questions</a></span></dt></dl></dd></dl></div><p>
|
||
This chapter contains information related to creating, uploading, maintaining,
|
||
and porting packages.
|
||
</p><div class="section" title="5.1. New packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="newpackage"></a>5.1. New packages</h2></div></div></div><p>
|
||
If you want to create a new package for the Debian distribution, you should
|
||
first check the <a class="ulink" href="http://www.debian.org/devel/wnpp/" target="_top">Work-Needing and
|
||
Prospective Packages (WNPP)</a> list. Checking the WNPP list ensures that
|
||
no one is already working on packaging that software, and that effort is not
|
||
duplicated. Read the <a class="ulink" href="http://www.debian.org/devel/wnpp/" target="_top">WNPP web
|
||
pages</a> for more information.
|
||
</p><p>
|
||
Assuming no one else is already working on your prospective package, you must
|
||
then submit a bug report (<a class="xref" href="beyond-pkging.html#submit-bug" title="7.1. Bug reporting">Section 7.1, “Bug reporting”</a>) against the
|
||
pseudo-package <code class="systemitem">wnpp</code> 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.
|
||
</p><p>
|
||
You should set the subject of the bug to <code class="literal">ITP:
|
||
<em class="replaceable"><code>foo</code></em> -- <em class="replaceable"><code>short
|
||
description</code></em></code>, substituting the name of the new
|
||
package for <em class="replaceable"><code>foo</code></em>.
|
||
The severity of the bug report must be set to <code class="literal">wishlist</code>.
|
||
Please send a copy to <code class="email"><<a class="email" href="mailto:debian-devel@lists.debian.org">debian-devel@lists.debian.org</a>></code> by using the X-Debbugs-CC
|
||
header (don't use CC:, because that way the message's subject won't
|
||
indicate the bug number). If you are packaging so many new packages (>10)
|
||
that notifying the mailing list in separate messages is too disruptive,
|
||
send a summary after filing the bugs to the debian-devel list instead.
|
||
This will inform the other developers about upcoming packages and will
|
||
allow a review of your description and package name.
|
||
</p><p>
|
||
Please include a <code class="literal">Closes: #<em class="replaceable"><code>nnnnn</code></em></code>
|
||
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 <a class="xref" href="pkgs.html#upload-bugfix" title="5.8.4. When bugs are closed by new uploads">Section 5.8.4, “When bugs are closed by new uploads”</a>).
|
||
</p><p>
|
||
If you think your package needs some explanations for the administrators of the
|
||
NEW package queue, include them in your changelog, send to <code class="email"><<a class="email" href="mailto:ftpmaster@debian.org">ftpmaster@debian.org</a>></code>
|
||
a reply to the email you receive as a maintainer after your upload, or reply to
|
||
the rejection email in case you are already re-uploading.
|
||
</p><p>
|
||
When closing security bugs include CVE numbers as well as the
|
||
<code class="literal">Closes: #<em class="replaceable"><code>nnnnn</code></em></code>.
|
||
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.
|
||
</p><p>
|
||
There are a number of reasons why we ask maintainers to announce their
|
||
intentions:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
It lets other people thinking about working on the package know that there
|
||
already is a volunteer, so efforts may be shared.
|
||
</p></li><li class="listitem"><p>
|
||
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 <code class="email"><<a class="email" href="mailto:debian-devel-changes@lists.debian.org">debian-devel-changes@lists.debian.org</a>></code>.
|
||
</p></li><li class="listitem"><p>
|
||
It is helpful to the people who live off <code class="literal">unstable</code> (and form
|
||
our first line of testers). We should encourage these people.
|
||
</p></li><li class="listitem"><p>
|
||
The announcements give maintainers and other interested parties a better feel
|
||
of what is going on, and what is new, in the project.
|
||
</p></li></ul></div><p>
|
||
Please see <a class="ulink" href="http://ftp-master.debian.org/REJECT-FAQ.html" target="_top">http://ftp-master.debian.org/REJECT-FAQ.html</a>
|
||
for common rejection reasons for a new package.
|
||
</p></div><div class="section" title="5.2. Recording changes in the package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="changelog-entries"></a>5.2. Recording changes in the package</h2></div></div></div><p>
|
||
Changes that you make to the package need to be recorded in the
|
||
<code class="filename">debian/changelog</code>. 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
|
||
<code class="filename">/usr/share/doc/<em class="replaceable"><code>package</code></em>/changelog.Debian.gz</code>,
|
||
or
|
||
<code class="filename">/usr/share/doc/<em class="replaceable"><code>package</code></em>/changelog.gz</code>
|
||
for native packages.
|
||
</p><p>
|
||
The <code class="filename">debian/changelog</code> file conforms to a certain structure,
|
||
with a number of different fields. One field of note, the
|
||
<code class="literal">distribution</code>, is described in <a class="xref" href="pkgs.html#distribution" title="5.5. Picking a distribution">Section 5.5, “Picking a distribution”</a>. More information about the structure of this file
|
||
can be found in the Debian Policy section titled
|
||
<code class="filename">debian/changelog</code>.
|
||
</p><p>
|
||
Changelog entries can be used to automatically close Debian bugs when the
|
||
package is installed into the archive. See <a class="xref" href="pkgs.html#upload-bugfix" title="5.8.4. When bugs are closed by new uploads">Section 5.8.4, “When bugs are closed by new uploads”</a>.
|
||
</p><p>
|
||
It is conventional that the changelog entry of a package that contains a new
|
||
upstream version of the software looks like this:
|
||
</p><pre class="screen">
|
||
* New upstream release.
|
||
</pre><p>
|
||
There are tools to help you create entries and finalize the
|
||
<code class="filename">changelog</code> for release — see <a class="xref" href="tools.html#devscripts" title="A.6.1. devscripts">Section A.6.1, “<code class="systemitem">devscripts</code>”</a>
|
||
and <a class="xref" href="tools.html#dpkg-dev-el" title="A.6.6. dpkg-dev-el">Section A.6.6, “<code class="systemitem">dpkg-dev-el</code>”</a>.
|
||
</p><p>
|
||
See also <a class="xref" href="best-pkging-practices.html#bpp-debian-changelog" title="6.3. Best practices for debian/changelog">Section 6.3, “Best practices for <code class="filename">debian/changelog</code>”</a>.
|
||
</p></div><div class="section" title="5.3. Testing the package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sanitycheck"></a>5.3. Testing the package</h2></div></div></div><p>
|
||
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):
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
Run <span class="command"><strong>lintian</strong></span> over the package. You can run
|
||
<span class="command"><strong>lintian</strong></span> as follows: <code class="literal">lintian -v
|
||
<em class="replaceable"><code>package-version</code></em>.changes</code>. This will check
|
||
the source package as well as the binary package. If you don't understand the
|
||
output that <span class="command"><strong>lintian</strong></span> generates, try adding the
|
||
<code class="literal">-i</code> switch, which will cause <span class="command"><strong>lintian</strong></span> to
|
||
output a very verbose description of the problem.
|
||
</p><p>
|
||
Normally, a package should <span class="emphasis"><em>not</em></span> be uploaded if it causes
|
||
<span class="command"><strong>lintian</strong></span> to emit errors (they will start with <code class="literal">E</code>).
|
||
</p><p>
|
||
For more information on <span class="command"><strong>lintian</strong></span>, see <a class="xref" href="tools.html#lintian" title="A.2.1. lintian">Section A.2.1, “<code class="systemitem">lintian</code>”</a>.
|
||
</p></li><li class="listitem"><p>
|
||
Optionally run <span class="command"><strong>debdiff</strong></span> (see <a class="xref" href="tools.html#debdiff" title="A.2.2. debdiff">Section A.2.2, “<span class="command"><strong>debdiff</strong></span>”</a>) to analyze changes from an older
|
||
version, if one exists.
|
||
</p></li><li class="listitem"><p>
|
||
Downgrade the package to the previous version (if one exists) — this tests
|
||
the <code class="filename">postrm</code> and <code class="filename">prerm</code> scripts.
|
||
</p></li><li class="listitem"><p>
|
||
Remove the package, then reinstall it.
|
||
</p></li><li class="listitem"><p>
|
||
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 <code class="filename">.diff.gz</code> file.
|
||
</p></li></ul></div></div><div class="section" title="5.4. Layout of the source package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sourcelayout"></a>5.4. Layout of the source package</h2></div></div></div><p>
|
||
There are two types of Debian source packages:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
the so-called <code class="literal">native</code> packages, where there is no
|
||
distinction between the original sources and the patches applied for Debian
|
||
</p></li><li class="listitem"><p>
|
||
the (more common) packages where there's an original source tarball file
|
||
accompanied by another file that contains the changes made by Debian
|
||
</p></li></ul></div><p>
|
||
For the native packages, the source package includes a Debian source control
|
||
file (<code class="filename">.dsc</code>) and the source tarball
|
||
(<code class="filename">.tar.{gz,bz2,xz}</code>). A source package of a non-native package
|
||
includes a Debian source control file, the original source tarball
|
||
(<code class="filename">.orig.tar.{gz,bz2,xz}</code>) and the Debian changes
|
||
(<code class="filename">.diff.gz</code> for the source format “1.0” or
|
||
<code class="filename">.debian.tar.{gz,bz2,xz}</code> for the source format “3.0 (quilt)”).
|
||
</p><p>
|
||
With source format “1.0”, whether a package is native or not was determined
|
||
by <span class="command"><strong>dpkg-source</strong></span> at build time. Nowadays it is recommended
|
||
to be explicit about the desired source format by putting either “3.0 (quilt)”
|
||
or “3.0 (native)” in <code class="filename">debian/source/format</code>.
|
||
The rest of this section relates only to non-native packages.
|
||
</p><p>
|
||
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
|
||
<code class="filename">.changes</code> file. Subsequently, this very same tar file
|
||
should be used to build the new diffs and <code class="filename">.dsc</code> files, and
|
||
will not need to be re-uploaded.
|
||
</p><p>
|
||
By default, <span class="command"><strong>dpkg-genchanges</strong></span> and
|
||
<span class="command"><strong>dpkg-buildpackage</strong></span> will include the original source tar file
|
||
if and only if the current changelog entry has a different upstream version
|
||
from the preceding entry. This behavior may be modified by using
|
||
<code class="literal">-sa</code> to always include it or <code class="literal">-sd</code> to always
|
||
leave it out.
|
||
</p><p>
|
||
If no original source is included in the upload, the original source tar-file
|
||
used by <span class="command"><strong>dpkg-source</strong></span> when constructing the
|
||
<code class="filename">.dsc</code> file and diff to be uploaded
|
||
<span class="emphasis"><em>must</em></span> be byte-for-byte identical with the one already in
|
||
the archive.
|
||
</p><p>
|
||
Please notice that, in non-native packages, permissions on files that are not
|
||
present in the <code class="filename">*.orig.tar.{gz,bz2,xz}</code> will not be preserved, as diff does not store file
|
||
permissions in the patch. However when using source format “3.0 (quilt)”,
|
||
permissions of files inside the <code class="filename">debian</code> directory are
|
||
preserved since they are stored in a tar archive.
|
||
</p></div><div class="section" title="5.5. Picking a distribution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="distribution"></a>5.5. Picking a distribution</h2></div></div></div><p>
|
||
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
|
||
<code class="filename">debian/changelog</code> file and places it in the
|
||
<code class="literal">Distribution</code> field of the <code class="filename">.changes</code> file.
|
||
</p><p>
|
||
There are several possible values for this field: <code class="literal">stable</code>,
|
||
<code class="literal">unstable</code>, <code class="literal">testing-proposed-updates</code> and
|
||
<code class="literal">experimental</code>. Normally, packages are uploaded into
|
||
<code class="literal">unstable</code>.
|
||
</p><p>
|
||
Actually, there are two other possible distributions: <code class="literal">stable-security</code>
|
||
and <code class="literal">testing-security</code>, but read
|
||
<a class="xref" href="pkgs.html#bug-security" title="5.8.5. Handling security-related bugs">Section 5.8.5, “Handling security-related bugs”</a> for more information on those.
|
||
</p><p>
|
||
It is not possible to upload a package into several distributions at the same
|
||
time.
|
||
</p><div class="section" title="5.5.1. Special case: uploads to the stable and oldstable distributions"><div class="titlepage"><div><div><h3 class="title"><a id="upload-stable"></a>5.5.1. Special case: uploads to the <code class="literal">stable</code> and
|
||
<code class="literal">oldstable</code> distributions</h3></div></div></div><p>
|
||
Uploading to <code class="literal">stable</code> means that the package will transferred
|
||
to the <code class="literal">proposed-updates-new</code> queue for review by the stable
|
||
release managers, and if approved will be installed in
|
||
<code class="filename">stable-proposed-updates</code> directory of the Debian archive.
|
||
From there, it will be included in <code class="literal">stable</code> with the next
|
||
point release.
|
||
</p><p>
|
||
To ensure that your upload will be accepted, you should discuss the changes
|
||
with the stable release team before you upload. For that, file a bug against
|
||
the <code class="systemitem">release.debian.org</code> pseudo-package
|
||
using <span class="command"><strong>reportbug</strong></span>, including the patch you want to
|
||
apply to the package version currently in <code class="literal">stable</code>. Always
|
||
be verbose and detailed in your changelog entries for uploads to the
|
||
<code class="literal">stable</code> distribution.
|
||
</p><p>
|
||
Extra care should be taken when uploading to <code class="literal">stable</code>.
|
||
Basically, a package should only be uploaded to <code class="literal">stable</code> if
|
||
one of the following happens:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
a truly critical functionality problem
|
||
</p></li><li class="listitem"><p>
|
||
the package becomes uninstallable
|
||
</p></li><li class="listitem"><p>
|
||
a released architecture lacks the package
|
||
</p></li></ul></div><p>
|
||
In the past, uploads to <code class="literal">stable</code> 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
|
||
<code class="filename">proposed-updates</code> archive when the advisory is released.
|
||
See <a class="xref" href="pkgs.html#bug-security" title="5.8.5. Handling security-related bugs">Section 5.8.5, “Handling security-related bugs”</a> for detailed information on handling
|
||
security problems. If the security teams deems the problem to be too
|
||
benign to be fixed through a <code class="literal">DSA</code>, the stable release
|
||
managers are usually willing to include your fix nonetheless in a regular
|
||
upload to <code class="literal">stable</code>.
|
||
</p><p>
|
||
Changing anything else in the package that isn't important is discouraged,
|
||
because even trivial fixes can cause bugs later on.
|
||
</p><p>
|
||
Packages uploaded to <code class="literal">stable</code> need to be compiled on systems
|
||
running <code class="literal">stable</code>, so that their dependencies are limited to
|
||
the libraries (and other packages) available in <code class="literal">stable</code>;
|
||
for example, a package uploaded to <code class="literal">stable</code> that depends on
|
||
a library package that only exists in <code class="literal">unstable</code> will be
|
||
rejected. Making changes to dependencies of other packages (by messing with
|
||
<code class="literal">Provides</code> or <code class="filename">shlibs</code> files), possibly
|
||
making those other packages uninstallable, is strongly discouraged.
|
||
</p><p>
|
||
Uploads to the <code class="literal">oldstable</code> distributions are possible as
|
||
long as it hasn't been archived. The same rules as for <code class="literal">stable</code>
|
||
apply.
|
||
</p></div><div class="section" title="5.5.2. Special case: uploads to testing/testing-proposed-updates"><div class="titlepage"><div><div><h3 class="title"><a id="upload-t-p-u"></a>5.5.2. Special case: uploads to <code class="literal">testing/testing-proposed-updates</code></h3></div></div></div><p>
|
||
Please see the information in the <a class="link" href="pkgs.html#t-p-u" title="5.13.3. Direct updates to testing">testing
|
||
section</a> for details.
|
||
</p></div></div><div class="section" title="5.6. Uploading a package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="upload"></a>5.6. Uploading a package</h2></div></div></div><div class="section" title="5.6.1. Uploading to ftp-master"><div class="titlepage"><div><div><h3 class="title"><a id="upload-ftp-master"></a>5.6.1. Uploading to <code class="literal">ftp-master</code></h3></div></div></div><p>
|
||
To upload a package, you should upload the files (including the signed changes
|
||
and dsc-file) with anonymous ftp to <code class="literal">ftp.upload.debian.org</code> in
|
||
the directory <a class="ulink" href="ftp://ftp.upload.debian.org/pub/UploadQueue/" target="_top">/pub/UploadQueue/</a>.
|
||
To get the files processed there, they need to be signed with a key in the
|
||
Debian Developers keyring or the Debian Maintainers keyring
|
||
(see <a class="ulink" href="http://wiki.debian.org/DebianMaintainer" target="_top">http://wiki.debian.org/DebianMaintainer</a>).
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
You may also find the Debian packages <a class="link" href="tools.html#dupload" title="A.5.1. dupload">dupload</a>
|
||
or <a class="link" href="tools.html#dput" title="A.5.2. dput">dput</a> useful when uploading packages.These
|
||
handy programs help automate the process of uploading packages into Debian.
|
||
</p><p>
|
||
For removing packages, please see
|
||
<a class="ulink" href="ftp://ftp.upload.debian.org/pub/UploadQueue/README" target="_top">ftp://ftp.upload.debian.org/pub/UploadQueue/README</a> and
|
||
the Debian package <a class="link" href="tools.html#dcut" title="A.5.3. dcut">dcut</a>.
|
||
</p></div><div class="section" title="5.6.2. Delayed uploads"><div class="titlepage"><div><div><h3 class="title"><a id="delayed-incoming"></a>5.6.2. Delayed uploads</h3></div></div></div><p>
|
||
It is sometimes useful to upload a package immediately, but to want this
|
||
package to arrive in the archive only a few days later. For example,
|
||
when preparing a <a class="link" href="pkgs.html#nmu" title="5.11. Non-Maintainer Uploads (NMUs)">Non-Maintainer Upload</a>,
|
||
you might want to give the maintainer a few days to react.
|
||
</p><p>
|
||
An upload to the delayed directory keeps the package in
|
||
<a class="ulink" href="http://ftp-master.debian.org/deferred.html" target="_top">the deferred uploads queue</a>.
|
||
When the specified waiting time is over, the package is moved into
|
||
the regular incoming directory for processing.
|
||
This is done through automatic uploading to
|
||
<code class="literal">ftp.upload.debian.org</code> in upload-directory
|
||
<code class="literal">DELAYED/<em class="replaceable"><code>X</code></em>-day</code>
|
||
(<em class="replaceable"><code>X</code></em> between 0 and 15). 0-day is uploaded
|
||
multiple times per day to <code class="literal">ftp.upload.debian.org</code>.
|
||
</p><p>
|
||
With dput, you can use the <code class="literal">--delayed <em class="replaceable"><code>DELAY</code></em></code>
|
||
parameter to put the package into one of the queues.
|
||
</p></div><div class="section" title="5.6.3. Security uploads"><div class="titlepage"><div><div><h3 class="title"><a id="s5.6.4"></a>5.6.3. Security uploads</h3></div></div></div><p>
|
||
Do <span class="strong"><strong>NOT</strong></span> upload a package to the security
|
||
upload queue (<code class="literal">oldstable-security</code>, <code class="literal">stable-security</code>,
|
||
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 <a class="xref" href="pkgs.html#bug-security" title="5.8.5. Handling security-related bugs">Section 5.8.5, “Handling security-related bugs”</a>.
|
||
</p></div><div class="section" title="5.6.4. Other upload queues"><div class="titlepage"><div><div><h3 class="title"><a id="s5.6.5"></a>5.6.4. Other upload queues</h3></div></div></div><p>
|
||
There is an alternative upload queue in Europe at <a class="ulink" href="ftp://ftp.eu.upload.debian.org/pub/UploadQueue/" target="_top">ftp://ftp.eu.upload.debian.org/pub/UploadQueue/</a>. It operates in
|
||
the same way as <code class="literal">ftp.upload.debian.org</code>, but should be faster
|
||
for European developers.
|
||
</p><p>
|
||
Packages can also be uploaded via ssh to
|
||
<code class="literal">ssh.upload.debian.org</code>; files should be put
|
||
<code class="literal">/srv/upload.debian.org/UploadQueue</code>. This queue does
|
||
not support <a class="link" href="pkgs.html#delayed-incoming" title="5.6.2. Delayed uploads">delayed uploads</a>.
|
||
</p></div><div class="section" title="5.6.5. Notification that a new package has been installed"><div class="titlepage"><div><div><h3 class="title"><a id="upload-notification"></a>5.6.5. Notification that a new package has been installed</h3></div></div></div><p>
|
||
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, <span class="command"><strong>dak process-upload</strong></span>. Specifically,
|
||
updates to existing packages to the <code class="literal">unstable</code> 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 some time to occur. Please
|
||
be patient.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
Note that if you upload via queues, the queue daemon software will also send
|
||
you a notification by email.
|
||
</p></div></div><div class="section" title="5.7. Specifying the package section, subsection and priority"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="override-file"></a>5.7. Specifying the package section, subsection and priority</h2></div></div></div><p>
|
||
The <code class="filename">debian/control</code> file's <code class="literal">Section</code> and
|
||
<code class="literal">Priority</code> 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 <code class="filename">debian/control</code> file are
|
||
actually just hints.
|
||
</p><p>
|
||
The archive maintainers keep track of the canonical sections and priorities for
|
||
packages in the <code class="literal">override file</code>. If there is a disparity
|
||
between the <code class="literal">override file</code> and the package's fields as
|
||
indicated in <code class="filename">debian/control</code>, then you will receive an
|
||
email noting the divergence when the package is installed into the archive.
|
||
You can either correct your <code class="filename">debian/control</code> file for your
|
||
next upload, or else you may wish to make a change in the <code class="literal">override
|
||
file</code>.
|
||
</p><p>
|
||
To alter the actual section that a package is put in, you need to first make
|
||
sure that the <code class="filename">debian/control</code> file in your package is
|
||
accurate. Next, submit a
|
||
bug against <code class="systemitem">ftp.debian.org</code> requesting
|
||
that the section or priority for your package be changed from the old section
|
||
or priority to the new one. Use a Subject like
|
||
<code class="literal">override: PACKAGE1:section/priority, [...],
|
||
PACKAGEX:section/priority</code>, and include the justification for the
|
||
change in the body of the bug report.
|
||
</p><p>
|
||
For more information about <code class="literal">override files</code>, see
|
||
<span class="citerefentry"><span class="refentrytitle">dpkg-scanpackages</span>(1)</span> and <a class="ulink" href="http://www.debian.org/Bugs/Developer#maintincorrect" target="_top">http://www.debian.org/Bugs/Developer#maintincorrect</a>.
|
||
</p><p>
|
||
Note that the <code class="literal">Section</code> field describes both the section as
|
||
well as the subsection, which are described in <a class="xref" href="resources.html#archive-sections" title="4.6.1. Sections">Section 4.6.1, “Sections”</a>. If the section is main, it should be omitted.
|
||
The list of allowable subsections can be found in <a class="ulink" href="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections" target="_top">http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections</a>.
|
||
</p></div><div class="section" title="5.8. Handling bugs"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="bug-handling"></a>5.8. Handling bugs</h2></div></div></div><p>
|
||
Every developer has to be able to work with the Debian <a class="ulink" href="http://www.debian.org/Bugs/" target="_top">bug tracking system</a>. This includes
|
||
knowing how to file bug reports properly (see <a class="xref" href="beyond-pkging.html#submit-bug" title="7.1. Bug reporting">Section 7.1, “Bug reporting”</a>),
|
||
how to update them and reorder them, and how to process and close them.
|
||
</p><p>
|
||
The bug tracking system's features are described in the <a class="ulink" href="http://www.debian.org/Bugs/Developer" target="_top">BTS documentation for
|
||
developers</a>. This includes closing bugs, sending followup messages,
|
||
assigning severities and tags, marking bugs as forwarded, and other issues.
|
||
</p><p>
|
||
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 <a class="ulink" href="http://www.debian.org/Bugs/server-control" target="_top">BTS control server
|
||
documentation</a>.
|
||
</p><div class="section" title="5.8.1. Monitoring bugs"><div class="titlepage"><div><div><h3 class="title"><a id="bug-monitoring"></a>5.8.1. Monitoring bugs</h3></div></div></div><p>
|
||
If you want to be a good maintainer, you should periodically check the <a class="ulink" href="http://www.debian.org/Bugs/" target="_top">Debian bug tracking system (BTS)</a> for
|
||
your packages. The BTS contains all the open bugs against your packages. You
|
||
can check them by browsing this page:
|
||
<code class="literal">http://bugs.debian.org/<em class="replaceable"><code>yourlogin</code></em>@debian.org</code>.
|
||
</p><p>
|
||
Maintainers interact with the BTS via email addresses at
|
||
<code class="literal">bugs.debian.org</code>. Documentation on available
|
||
commands can be found at <a class="ulink" href="http://www.debian.org/Bugs/" target="_top">http://www.debian.org/Bugs/</a>, or,
|
||
if you have installed the <code class="systemitem">doc-debian</code>
|
||
package, you can look at the local files <code class="filename">/usr/share/doc/debian/bug-*</code>.
|
||
</p><p>
|
||
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:
|
||
</p><pre class="screen">
|
||
# ask for weekly reports of bugs in my packages
|
||
0 17 * * fri echo "index maint <em class="replaceable"><code>address</code></em>" | mail request@bugs.debian.org
|
||
</pre><p>
|
||
Replace <em class="replaceable"><code>address</code></em> with your official Debian maintainer
|
||
address.
|
||
</p></div><div class="section" title="5.8.2. Responding to bugs"><div class="titlepage"><div><div><h3 class="title"><a id="bug-answering"></a>5.8.2. Responding to bugs</h3></div></div></div><p>
|
||
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.,
|
||
<code class="email"><<a class="email" href="mailto:123@bugs.debian.org"><em class="replaceable"><code>123</code></em>@bugs.debian.org</a>></code>). If you're writing a new mail and you
|
||
don't remember the submitter email address, you can use the
|
||
<code class="email"><<a class="email" href="mailto:123-submitter@bugs.debian.org"><em class="replaceable"><code>123</code></em>-submitter@bugs.debian.org</a>></code> email to contact the submitter
|
||
<span class="emphasis"><em>and</em></span> to record your mail within the bug log (that means you
|
||
don't need to send a copy of the mail to <code class="email"><<a class="email" href="mailto:123@bugs.debian.org"><em class="replaceable"><code>123</code></em>@bugs.debian.org</a>></code>).
|
||
</p><p>
|
||
If you get a bug which mentions FTBFS, this means Fails to build from source.
|
||
Porters frequently use this acronym.
|
||
</p><p>
|
||
Once you've dealt with a bug report (e.g. fixed it), mark it as
|
||
<code class="literal">done</code> (close it) by sending an explanation message to
|
||
<code class="email"><<a class="email" href="mailto:123-done@bugs.debian.org"><em class="replaceable"><code>123</code></em>-done@bugs.debian.org</a>></code>. If you're fixing a bug by changing
|
||
and uploading the package, you can automate bug closing as described in <a class="xref" href="pkgs.html#upload-bugfix" title="5.8.4. When bugs are closed by new uploads">Section 5.8.4, “When bugs are closed by new uploads”</a>.
|
||
</p><p>
|
||
You should <span class="emphasis"><em>never</em></span> close bugs via the bug server
|
||
<code class="literal">close</code> command sent to <code class="email"><<a class="email" href="mailto:control@bugs.debian.org">control@bugs.debian.org</a>></code>.
|
||
If you do so, the original submitter will not receive any information about why
|
||
the bug was closed.
|
||
</p></div><div class="section" title="5.8.3. Bug housekeeping"><div class="titlepage"><div><div><h3 class="title"><a id="bug-housekeeping"></a>5.8.3. Bug housekeeping</h3></div></div></div><p>
|
||
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 <a class="ulink" href="http://www.debian.org/Bugs/Developer" target="_top">BTS documentation for Debian
|
||
developers</a>. Operations such as reassigning, merging, and tagging bug
|
||
reports are described in the <a class="ulink" href="http://www.debian.org/Bugs/server-control" target="_top">BTS control server
|
||
documentation</a>. This section contains some guidelines for managing your
|
||
own bugs, based on the collective Debian developer experience.
|
||
</p><p>
|
||
Filing bugs for problems that you find in other packages is one of the civic
|
||
obligations of maintainership, see <a class="xref" href="beyond-pkging.html#submit-bug" title="7.1. Bug reporting">Section 7.1, “Bug reporting”</a> for details.
|
||
However, handling the bugs in your own packages is even more important.
|
||
</p><p>
|
||
Here's a list of steps that you may follow to handle a bug report:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
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.
|
||
</p><p>
|
||
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 <code class="literal">wontfix</code> 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 <code class="systemitem">tech-ctte</code> (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 <a class="ulink" href="http://www.debian.org/devel/tech-ctte" target="_top">recommended
|
||
procedure</a>.
|
||
</p></li><li class="listitem"><p>
|
||
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 <a class="link" href="resources.html#irc-channels" title="4.2. IRC channels">IRC</a> or
|
||
on <code class="email"><<a class="email" href="mailto:debian-devel@lists.debian.org">debian-devel@lists.debian.org</a>></code>. Please inform the maintainer(s) of the package
|
||
you reassign the bug to, for example by Cc:ing the message that does the
|
||
reassign to <code class="email"><<a class="email" href="mailto:packagename@packages.debian.org"><em class="replaceable"><code>packagename</code></em>@packages.debian.org</a>></code> and explaining
|
||
your reasons in that mail. Please note that a simple reassignment is
|
||
<span class="emphasis"><em>not</em></span> e-mailed to the maintainers of the package
|
||
being reassigned to, so they won't know about it until they look at
|
||
a bug overview for their packages.
|
||
</p><p>
|
||
If the bug affects the operation of your package, please consider
|
||
cloning the bug and reassigning the clone to the package that really
|
||
causes the behavior. Otherwise, the bug will not be shown in your
|
||
package's bug list, possibly causing users to report the same bug over
|
||
and over again. You should block "your" bug with the reassigned, cloned
|
||
bug to document the relationship.
|
||
</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
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
|
||
<code class="literal">moreinfo</code> tag to mark the bug as such. Moreover if you can't
|
||
reproduce the bug, you tag it <code class="literal">unreproducible</code>. 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.
|
||
</p></li><li class="listitem"><p>
|
||
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 <code class="literal">help</code>. You can also
|
||
ask for help on <code class="email"><<a class="email" href="mailto:debian-devel@lists.debian.org">debian-devel@lists.debian.org</a>></code> or
|
||
<code class="email"><<a class="email" href="mailto:debian-qa@lists.debian.org">debian-qa@lists.debian.org</a>></code>. 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 <code class="literal">patch</code>.
|
||
</p></li><li class="listitem"><p>
|
||
If you have fixed a bug in your local copy, or if a fix has been committed to
|
||
the VCS repository, you may tag the bug as <code class="literal">pending</code> to let
|
||
people know that the bug is corrected and that it will be closed with the next
|
||
upload (add the <code class="literal">closes:</code> in the
|
||
<code class="filename">changelog</code>). This is particularly useful if you are
|
||
several developers working on the same package.
|
||
</p></li><li class="listitem"><p>
|
||
Once a corrected package is available in the archive, the bug should be
|
||
closed indicating the version in which it was fixed. This can be done
|
||
automatically, read <a class="xref" href="pkgs.html#upload-bugfix" title="5.8.4. When bugs are closed by new uploads">Section 5.8.4, “When bugs are closed by new uploads”</a>.
|
||
</p></li></ol></div></div><div class="section" title="5.8.4. When bugs are closed by new uploads"><div class="titlepage"><div><div><h3 class="title"><a id="upload-bugfix"></a>5.8.4. When bugs are closed by new uploads</h3></div></div></div><p>
|
||
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.
|
||
</p><p>
|
||
However, it's possible to avoid having to manually close bugs after the upload
|
||
— just list the fixed bugs in your <code class="filename">debian/changelog</code>
|
||
file, following a certain syntax, and the archive maintenance software will
|
||
close the bugs for you. For example:
|
||
</p><pre class="screen">
|
||
acme-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.
|
||
</pre><p>
|
||
Technically speaking, the following Perl regular expression describes how bug
|
||
closing changelogs are identified:
|
||
</p><pre class="screen">
|
||
/closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
|
||
</pre><p>
|
||
We prefer the <code class="literal">closes: #<em class="replaceable"><code>XXX</code></em></code>
|
||
syntax, as it is the most concise entry and the easiest to integrate with the
|
||
text of the <code class="filename">changelog</code>. Unless specified different by the
|
||
<code class="literal">-v</code>-switch to <span class="command"><strong>dpkg-buildpackage</strong></span>,
|
||
only the bugs closed in the most recent changelog entry are closed (basically,
|
||
exactly the bugs mentioned in the changelog-part in the
|
||
<code class="filename">.changes</code> file are closed).
|
||
</p><p>
|
||
Historically, uploads identified as <a class="link" href="pkgs.html#nmu" title="5.11. Non-Maintainer Uploads (NMUs)">non-maintainer
|
||
upload (NMU)</a> were tagged <code class="literal">fixed</code> instead of being
|
||
closed, but that practice was ceased with the advent of version-tracking. The
|
||
same applied to the tag <code class="literal">fixed-in-experimental</code>.
|
||
</p><p>
|
||
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 <code class="literal">reopen <em class="replaceable"><code>XXX</code></em></code> command
|
||
to the bug tracking system's control address,
|
||
<code class="email"><<a class="email" href="mailto:control@bugs.debian.org">control@bugs.debian.org</a>></code>. To close any remaining bugs that were
|
||
fixed by your upload, email the <code class="filename">.changes</code> file to
|
||
<code class="email"><<a class="email" href="mailto:XXX-done@bugs.debian.org"><em class="replaceable"><code>XXX</code></em>-done@bugs.debian.org</a>></code>, where <em class="replaceable"><code>XXX</code></em>
|
||
is the bug number, and put Version: <em class="replaceable"><code>YYY</code></em> and an empty line as the first two
|
||
lines of the body of the email, where <em class="replaceable"><code>YYY</code></em> is the
|
||
first version where the bug has been fixed.
|
||
</p><p>
|
||
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
|
||
<code class="email"><<a class="email" href="mailto:XXX-done@bugs.debian.org"><em class="replaceable"><code>XXX</code></em>-done@bugs.debian.org</a>></code>. Do <span class="strong"><strong>not</strong></span> 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.
|
||
</p><p>
|
||
For general information on how to write your changelog entries, see <a class="xref" href="best-pkging-practices.html#bpp-debian-changelog" title="6.3. Best practices for debian/changelog">Section 6.3, “Best practices for <code class="filename">debian/changelog</code>”</a>.
|
||
</p></div><div class="section" title="5.8.5. Handling security-related bugs"><div class="titlepage"><div><div><h3 class="title"><a id="bug-security"></a>5.8.5. Handling security-related bugs</h3></div></div></div><p>
|
||
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
|
||
<code class="literal">security.debian.org</code>.
|
||
</p><p>
|
||
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, preferably by filing a ticket in
|
||
their Request Tracker.
|
||
See <a class="ulink" href="http://wiki.debian.org/rt.debian.org#Security_Team" target="_top">http://wiki.debian.org/rt.debian.org#Security_Team</a>.
|
||
Alternatively you may email <code class="email"><<a class="email" href="mailto:team@security.debian.org">team@security.debian.org</a>></code>.
|
||
<span class="strong"><strong>DO NOT UPLOAD</strong></span> any packages for
|
||
<code class="literal">stable</code> without contacting the team. Useful information
|
||
includes, for example:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
Whether or not the bug is already public.
|
||
</p></li><li class="listitem"><p>
|
||
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
|
||
<code class="literal">testing</code> and <code class="literal">unstable</code>.
|
||
</p></li><li class="listitem"><p>
|
||
The nature of the fix, if any is available (patches are especially helpful)
|
||
</p></li><li class="listitem"><p>
|
||
Any fixed packages that you have prepared yourself (send only the
|
||
<code class="filename">.diff.gz</code> and <code class="filename">.dsc</code> files and read <a class="xref" href="pkgs.html#bug-security-building" title="5.8.5.4. Preparing packages to address security issues">Section 5.8.5.4, “Preparing packages to address security issues”</a> first)
|
||
</p></li><li class="listitem"><p>
|
||
Any assistance you can provide to help with testing (exploits, regression
|
||
testing, etc.)
|
||
</p></li><li class="listitem"><p>
|
||
Any information needed for the advisory (see <a class="xref" href="pkgs.html#bug-security-advisories" title="5.8.5.3. Security Advisories">Section 5.8.5.3, “Security Advisories”</a>)
|
||
</p></li></ul></div><p>As the maintainer of the package, you have the responsibility to
|
||
maintain it, even in the stable release. You are in the best position
|
||
to evaluate patches and test updated packages, so please see the sections
|
||
below on how to prepare packages for the Security Team to handle.</p><div class="section" title="5.8.5.1. The Security Tracker"><div class="titlepage"><div><div><h4 class="title"><a id="bug-security-tracker"></a>5.8.5.1. The Security Tracker</h4></div></div></div><p>
|
||
The security team maintains a central database, the
|
||
<a class="ulink" href="http://security-tracker.debian.org/" target="_top">Debian Security Tracker</a>.
|
||
This contains all public information that is known about security issues:
|
||
which packages and versions are affected or fixed, and thus whether stable,
|
||
testing and/or unstable are vulnerable. Information that is still confidential
|
||
is not added to the tracker.
|
||
</p><p>
|
||
You can search it for a specific issue, but also on package name. Look
|
||
for your package to see which issues are still open. If you can, please provide
|
||
more information about those issues, or help to address them in your package.
|
||
Instructions are on the tracker web pages.
|
||
</p></div><div class="section" title="5.8.5.2. Confidentiality"><div class="titlepage"><div><div><h4 class="title"><a id="bug-security-confidentiality"></a>5.8.5.2. Confidentiality</h4></div></div></div><p>
|
||
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.
|
||
</p><p>
|
||
There are several ways developers can learn of a security problem:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
they notice it on a public forum (mailing list, web site, etc.)
|
||
</p></li><li class="listitem"><p>
|
||
someone files a bug report
|
||
</p></li><li class="listitem"><p>
|
||
someone informs them via private email
|
||
</p></li></ul></div><p>
|
||
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:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li></ul></div><p>
|
||
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.
|
||
</p><p>
|
||
Please note that if secrecy is needed you may not upload a fix to
|
||
<code class="literal">unstable</code> (or
|
||
anywhere else, such as a public VCS 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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
The Security Team has a PGP-key to enable encrypted communication about
|
||
sensitive issues. See the <a class="ulink" href="http://www.debian.org/security/faq#contact" target="_top">Security Team FAQ</a> for details.
|
||
</p></div><div class="section" title="5.8.5.3. Security Advisories"><div class="titlepage"><div><div><h4 class="title"><a id="bug-security-advisories"></a>5.8.5.3. Security Advisories</h4></div></div></div><p>
|
||
Security advisories are only issued for the current, released stable
|
||
distribution, and <span class="emphasis"><em>not</em></span> for <code class="literal">testing</code>
|
||
or <code class="literal">unstable</code>. When released, advisories are sent to the
|
||
<code class="email"><<a class="email" href="mailto:debian-security-announce@lists.debian.org">debian-security-announce@lists.debian.org</a>></code> mailing list and posted on
|
||
<a class="ulink" href="http://www.debian.org/security/" target="_top">the security web
|
||
page</a>. 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:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
A description of the problem and its scope, including:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p>
|
||
The type of problem (privilege escalation, denial of service, etc.)
|
||
</p></li><li class="listitem"><p>
|
||
What privileges may be gained, and by whom (if any)
|
||
</p></li><li class="listitem"><p>
|
||
How it can be exploited
|
||
</p></li><li class="listitem"><p>
|
||
Whether it is remotely or locally exploitable
|
||
</p></li><li class="listitem"><p>
|
||
How the problem was fixed
|
||
</p></li></ul></div><p>
|
||
This information allows users to assess the threat to their systems.
|
||
</p></li><li class="listitem"><p>
|
||
Version numbers of affected packages
|
||
</p></li><li class="listitem"><p>
|
||
Version numbers of fixed packages
|
||
</p></li><li class="listitem"><p>
|
||
Information on where to obtain the updated packages (usually from the Debian
|
||
security archive)
|
||
</p></li><li class="listitem"><p>
|
||
References to upstream advisories, <a class="ulink" href="http://cve.mitre.org" target="_top">CVE</a> identifiers, and any other information
|
||
useful in cross-referencing the vulnerability
|
||
</p></li></ul></div></div><div class="section" title="5.8.5.4. Preparing packages to address security issues"><div class="titlepage"><div><div><h4 class="title"><a id="bug-security-building"></a>5.8.5.4. Preparing packages to address security issues</h4></div></div></div><p>
|
||
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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
Do <span class="strong"><strong>NOT</strong></span> 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.
|
||
</p><p>
|
||
Review and test your changes as much as possible. Check the differences from
|
||
the previous version repeatedly (<span class="command"><strong>interdiff</strong></span> from the
|
||
<code class="systemitem">patchutils</code> package and
|
||
<span class="command"><strong>debdiff</strong></span> from <code class="systemitem">devscripts</code> are useful tools for this, see <a class="xref" href="tools.html#debdiff" title="A.2.2. debdiff">Section A.2.2, “<span class="command"><strong>debdiff</strong></span>”</a>).
|
||
</p><p>
|
||
Be sure to verify the following items:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
<span class="strong"><strong>Target the right distribution</strong></span>
|
||
in your <code class="filename">debian/changelog</code>.
|
||
For <code class="literal">stable</code> this is <code class="literal">stable-security</code> and
|
||
for <code class="literal">testing</code> this is <code class="literal">testing-security</code>, and for the previous
|
||
stable release, this is <code class="literal">oldstable-security</code>. Do not target
|
||
<em class="replaceable"><code>distribution</code></em><code class="literal">-proposed-updates</code> or
|
||
<code class="literal">stable</code>!
|
||
</p></li><li class="listitem"><p>
|
||
The upload should have <span class="strong"><strong>urgency=high</strong></span>.
|
||
</p></li><li class="listitem"><p>
|
||
Make descriptive, meaningful changelog entries. Others will rely on them to
|
||
determine whether a particular bug was fixed. Add <code class="literal">closes:</code>
|
||
statements for any <span class="strong"><strong>Debian bugs</strong></span> filed.
|
||
Always include an external reference, preferably a <span class="strong"><strong>CVE
|
||
identifier</strong></span>, so that it can be cross-referenced. However, if a CVE
|
||
identifier has not yet been assigned, do not wait for it but continue the
|
||
process. The identifier can be cross-referenced later.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure the <span class="strong"><strong>version number</strong></span> is proper.
|
||
It must be greater than the current package, but less than package versions in
|
||
later distributions. If in doubt, test it with <code class="literal">dpkg
|
||
--compare-versions</code>. Be careful not to re-use a version number that
|
||
you have already used for a previous upload, or one that conflicts with a
|
||
binNMU. The convention is to append
|
||
<code class="literal">+</code><em class="replaceable"><code>codename</code></em><code class="literal">1</code>, e.g.
|
||
<code class="literal">1:2.4.3-4+lenny1</code>, of course increasing 1 for any subsequent
|
||
uploads.
|
||
</p></li><li class="listitem"><p>
|
||
Unless the upstream source has been uploaded to
|
||
<code class="literal">security.debian.org</code> before (by a previous security update),
|
||
build the upload <span class="strong"><strong>with full upstream source</strong></span>
|
||
(<code class="literal">dpkg-buildpackage -sa</code>). If there has been a previous
|
||
upload to <code class="literal">security.debian.org</code> with the same upstream
|
||
version, you may upload without upstream source (<code class="literal">dpkg-buildpackage
|
||
-sd</code>).
|
||
</p></li><li class="listitem"><p>
|
||
Be sure to use the <span class="strong"><strong>exact same
|
||
<code class="filename">*.orig.tar.{gz,bz2,xz}</code></strong></span> as used in the
|
||
normal archive, otherwise it is not possible to move the security fix into the
|
||
main archives later.
|
||
</p></li><li class="listitem"><p>
|
||
Build the package on a <span class="strong"><strong>clean system</strong></span> 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
|
||
<a class="xref" href="resources.html#server-machines" title="4.4. Debian machines">Section 4.4, “Debian machines”</a>) or setup a chroot (see
|
||
<a class="xref" href="tools.html#pbuilder" title="A.4.3. pbuilder">Section A.4.3, “<code class="systemitem">pbuilder</code>”</a> and <a class="xref" href="tools.html#debootstrap" title="A.4.2. debootstrap">Section A.4.2, “<code class="systemitem">debootstrap</code>”</a>).
|
||
</p></li></ul></div></div><div class="section" title="5.8.5.5. Uploading the fixed package"><div class="titlepage"><div><div><h4 class="title"><a id="bug-security-upload"></a>5.8.5.5. Uploading the fixed package</h4></div></div></div><p>
|
||
Do <span class="strong"><strong>NOT</strong></span> upload a package to the security
|
||
upload queue (<code class="literal">oldstable-security</code>, <code class="literal">stable-security</code>,
|
||
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.
|
||
</p><p>
|
||
Do <span class="strong"><strong>NOT</strong></span> upload your fix to
|
||
<code class="literal">proposed-updates</code> without coordinating with the security team.
|
||
Packages from <code class="literal">security.debian.org</code> will be copied into
|
||
the <code class="literal">proposed-updates</code> 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.
|
||
</p><p>
|
||
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
|
||
<code class="literal">ftp://security-master.debian.org/pub/SecurityUploadQueue/</code>.
|
||
</p><p>
|
||
Once an upload to the security queue has been accepted, the package will
|
||
automatically be built for all architectures and stored for verification by
|
||
the security team.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
If a member of the security team accepts a package, it will be installed on
|
||
<code class="literal">security.debian.org</code> as well as proposed for the proper
|
||
<em class="replaceable"><code>distribution</code></em><code class="literal">-proposed-updates</code>
|
||
on <code class="literal">ftp-master.debian.org</code>.
|
||
</p></div></div></div><div class="section" title="5.9. Moving, removing, renaming, adopting, and orphaning packages"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="archive-manip"></a>5.9. Moving, removing, renaming, adopting, and orphaning packages</h2></div></div></div><p>
|
||
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.
|
||
</p><div class="section" title="5.9.1. Moving packages"><div class="titlepage"><div><div><h3 class="title"><a id="moving-pkgs"></a>5.9.1. Moving packages</h3></div></div></div><p>
|
||
Sometimes a package will change its section. For instance, a package from the
|
||
<code class="literal">non-free</code> section might be GPL'd in a later version, in which case the package
|
||
should be moved to `main' or `contrib'.<sup>[<a id="idp20423976" href="#ftn.idp20423976" class="footnote">3</a>]</sup>
|
||
</p><p>
|
||
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 <a class="ulink" href="http://www.debian.org/doc/debian-policy/" target="_top">Debian Policy Manual</a> for
|
||
details). You must ensure that you include the
|
||
<code class="filename">.orig.tar.{gz,bz2,xz}</code> 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.
|
||
</p><p>
|
||
If, on the other hand, you need to change the <code class="literal">subsection</code>
|
||
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 <a class="xref" href="pkgs.html#override-file" title="5.7. Specifying the package section, subsection and priority">Section 5.7, “Specifying the package section, subsection and priority”</a>.
|
||
</p></div><div class="section" title="5.9.2. Removing packages"><div class="titlepage"><div><div><h3 class="title"><a id="removing-pkgs"></a>5.9.2. Removing packages</h3></div></div></div><p>
|
||
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 <code class="systemitem">ftp.debian.org</code> asking that the package be removed;
|
||
as all bugs, this bug should normally have normal severity.
|
||
The bug title should be in the form <code class="literal">RM: <em class="replaceable"><code>package</code></em>
|
||
<em class="replaceable"><code>[architecture list]</code></em> --
|
||
<em class="replaceable"><code>reason</code></em></code>, where <em class="replaceable"><code>package</code></em>
|
||
is the package to be removed and <em class="replaceable"><code>reason</code></em> is a
|
||
short summary of the reason for the removal request.
|
||
<em class="replaceable"><code>[architecture list]</code></em> is optional and only needed
|
||
if the removal request only applies to some architectures, not all. Note
|
||
that the <span class="command"><strong>reportbug</strong></span> will create a title conforming
|
||
to these rules when you use it to report a bug against the
|
||
<code class="systemitem">ftp.debian.org</code> pseudo-package.
|
||
</p><p>
|
||
If you want to remove a package you maintain, you should note this in
|
||
the bug title by prepending <code class="literal">ROM</code> (Request Of Maintainer).
|
||
There are several other standard acronyms used in the reasoning for a package
|
||
removal, see <a class="ulink" href="http://ftp-master.debian.org/removals.html" target="_top">http://ftp-master.debian.org/removals.html</a>
|
||
for a complete list. That page also provides a convenient overview of
|
||
pending removal requests.
|
||
</p><p>
|
||
Note that removals can only be done for the <code class="literal">unstable</code>,
|
||
<code class="literal">experimental</code> and <code class="literal">stable</code>
|
||
distribution. Packages are not removed from
|
||
<code class="literal">testing</code> directly. Rather, they will be removed
|
||
automatically after the package has been removed from
|
||
<code class="literal">unstable</code> and no package in
|
||
<code class="literal">testing</code> depends on it.
|
||
</p><p>
|
||
There is one exception when an explicit removal request is not necessary: If a
|
||
(source or binary) package is no longer built from source, 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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
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. Should the package be orphaned and thus have no maintainer,
|
||
you should first discuss the removal request on <code class="email"><<a class="email" href="mailto:debian-qa@lists.debian.org">debian-qa@lists.debian.org</a>></code>. If
|
||
there is a consensus that the package should be removed, you should
|
||
reassign and retitle the <code class="literal">O:</code> bug filed against the
|
||
<code class="literal">wnpp</code> package instead of filing a new bug as
|
||
removal request.
|
||
</p><p>
|
||
Further information relating to these and other package removal related topics
|
||
may be found at <a class="ulink" href="http://wiki.debian.org/ftpmaster_Removals" target="_top">http://wiki.debian.org/ftpmaster_Removals</a>
|
||
and <a class="ulink" href="http://qa.debian.org/howto-remove.html" target="_top">http://qa.debian.org/howto-remove.html</a>.
|
||
</p><p>
|
||
If in doubt concerning whether a package is disposable, email
|
||
<code class="email"><<a class="email" href="mailto:debian-devel@lists.debian.org">debian-devel@lists.debian.org</a>></code> asking for opinions. Also of interest is
|
||
the <span class="command"><strong>apt-cache</strong></span> program from the <code class="systemitem">apt</code> package. When invoked as <code class="literal">apt-cache
|
||
showpkg <em class="replaceable"><code>package</code></em></code>, the program will show
|
||
details for <em class="replaceable"><code>package</code></em>, including reverse depends.
|
||
Other useful programs include <span class="command"><strong>apt-cache rdepends</strong></span>,
|
||
<span class="command"><strong>apt-rdepends</strong></span>, <span class="command"><strong>build-rdeps</strong></span> (in the
|
||
<code class="systemitem">devscripts</code> package) and
|
||
<span class="command"><strong>grep-dctrl</strong></span>. Removal of
|
||
orphaned packages is discussed on <code class="email"><<a class="email" href="mailto:debian-qa@lists.debian.org">debian-qa@lists.debian.org</a>></code>.
|
||
</p><p>
|
||
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. <code class="literal">libfoo12</code> was
|
||
removed because <code class="literal">libfoo13</code> supersedes it) or closed if the
|
||
software is simply no longer part of Debian.
|
||
When closing the bugs,
|
||
to avoid marking the bugs as fixed in versions of the packages
|
||
in previous Debian releases, they should be marked as fixed
|
||
in the version <code class="literal"><most-recent-version-ever-in-Debian>+rm</code>.
|
||
</p><div class="section" title="5.9.2.1. Removing packages from Incoming"><div class="titlepage"><div><div><h4 class="title"><a id="s5.9.2.1"></a>5.9.2.1. Removing packages from <code class="filename">Incoming</code></h4></div></div></div><p>
|
||
In the past, it was possible to remove packages from
|
||
<code class="filename">incoming</code>. 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 <code class="literal">unstable</code> 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.
|
||
</p></div></div><div class="section" title="5.9.3. Replacing or renaming packages"><div class="titlepage"><div><div><h3 class="title"><a id="s5.9.3"></a>5.9.3. Replacing or renaming packages</h3></div></div></div><p>
|
||
When the upstream maintainers for one of your packages chose to
|
||
rename their software (or you made a mistake naming your package),
|
||
you should follow a two-step process to rename it. In the first
|
||
step, change the <code class="filename">debian/control</code> file to
|
||
reflect the new name and to replace, provide and conflict with the
|
||
obsolete package name (see the <a class="ulink" href="http://www.debian.org/doc/debian-policy/" target="_top">Debian
|
||
Policy Manual</a> for details). Please note that you
|
||
should only add a <code class="literal">Provides</code> relation if all
|
||
packages depending on the obsolete package name continue to work
|
||
after the renaming. Once you've uploaded the package and the package
|
||
has moved into the archive, file a bug against <code class="systemitem">ftp.debian.org</code>
|
||
asking to remove the package with the
|
||
obsolete name (see <a class="xref" href="pkgs.html#removing-pkgs" title="5.9.2. Removing packages">Section 5.9.2, “Removing packages”</a>). Do not forget
|
||
to properly reassign the package's bugs at the same time.
|
||
</p><p>
|
||
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
|
||
<code class="filename">foo_1.00.orig.tar.gz</code> with
|
||
<code class="filename">foo_1.00+0.orig.tar.gz</code> or
|
||
<code class="filename">foo_1.00.orig.tar.bz2</code>. This restriction gives each
|
||
file on the ftp site a unique name, which helps to ensure consistency
|
||
across the mirror network.
|
||
</p></div><div class="section" title="5.9.4. Orphaning a package"><div class="titlepage"><div><div><h3 class="title"><a id="orphaning"></a>5.9.4. Orphaning a package</h3></div></div></div><p>
|
||
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 <code class="literal">Debian QA Group <packages@qa.debian.org></code> and
|
||
submit a bug report against the pseudo package <code class="systemitem">wnpp</code>. The bug report should be titled <code class="literal">O:
|
||
<em class="replaceable"><code>package</code></em> -- <em class="replaceable"><code>short
|
||
description</code></em></code> indicating that the package is now
|
||
orphaned. The severity of the bug should be set to
|
||
<code class="literal">normal</code>; 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 <code class="email"><<a class="email" href="mailto:debian-devel@lists.debian.org">debian-devel@lists.debian.org</a>></code> 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).
|
||
</p><p>
|
||
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 <code class="systemitem">wnpp</code> and title it <code class="literal">RFA:
|
||
<em class="replaceable"><code>package</code></em> -- <em class="replaceable"><code>short
|
||
description</code></em></code>. <code class="literal">RFA</code> stands for
|
||
<code class="literal">Request For Adoption</code>.
|
||
</p><p>
|
||
More information is on the <a class="ulink" href="http://www.debian.org/devel/wnpp/" target="_top">WNPP
|
||
web pages</a>.
|
||
</p></div><div class="section" title="5.9.5. Adopting a package"><div class="titlepage"><div><div><h3 class="title"><a id="adopting"></a>5.9.5. Adopting a package</h3></div></div></div><p>
|
||
A list of packages in need of a new maintainer is available in the <a class="ulink" href="http://www.debian.org/devel/wnpp/" target="_top">Work-Needing and Prospective Packages
|
||
list (WNPP)</a>. 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.
|
||
</p><p>
|
||
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 <a class="xref" href="beyond-pkging.html#mia-qa" title="7.4. Dealing with inactive and/or unreachable maintainers">Section 7.4, “Dealing with inactive and/or unreachable maintainers”</a>.
|
||
</p><p>
|
||
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 <a class="ulink" href="http://www.debian.org/devel/tech-ctte" target="_top">technical committee web page</a> for
|
||
more information).
|
||
</p><p>
|
||
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
|
||
<code class="literal">Maintainer</code> 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 <a class="xref" href="resources.html#pkg-tracking-system" title="4.10. The Package Tracking System">Section 4.10, “The Package Tracking System”</a> 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.
|
||
</p></div></div><div class="section" title="5.10. Porting and being ported"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="porting"></a>5.10. Porting and being ported</h2></div></div></div><p>
|
||
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.
|
||
</p><p>
|
||
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, when a maintainer
|
||
uploads a (portable) source packages with binaries for the <code class="literal">i386</code>
|
||
architecture, it will be built for each of the other architectures,
|
||
amounting to 11 more builds.
|
||
</p><div class="section" title="5.10.1. Being kind to porters"><div class="titlepage"><div><div><h3 class="title"><a id="kind-to-porters"></a>5.10.1. Being kind to porters</h3></div></div></div><p>
|
||
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.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
By far, most of the problems encountered by porters are caused by
|
||
<span class="emphasis"><em>packaging bugs</em></span> in the source packages. Here is a
|
||
checklist of things you should check or be aware of.
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Make sure that your <code class="literal">Build-Depends</code> and
|
||
<code class="literal">Build-Depends-Indep</code> settings in
|
||
<code class="filename">debian/control</code> are set properly. The best way to validate
|
||
this is to use the <code class="systemitem">debootstrap</code> package
|
||
to create an <code class="literal">unstable</code> chroot environment (see <a class="xref" href="tools.html#debootstrap" title="A.4.2. debootstrap">Section A.4.2, “<code class="systemitem">debootstrap</code>”</a>).
|
||
Within that chrooted environment, install the <code class="systemitem">build-essential</code> package and any package
|
||
dependencies mentioned in <code class="literal">Build-Depends</code> and/or
|
||
<code class="literal">Build-Depends-Indep</code>. Finally, try building your package
|
||
within that chrooted environment. These steps can be automated by the use of
|
||
the <span class="command"><strong>pbuilder</strong></span> program which is provided by the package of the
|
||
same name (see <a class="xref" href="tools.html#pbuilder" title="A.4.3. pbuilder">Section A.4.3, “<code class="systemitem">pbuilder</code>”</a>).
|
||
</p><p>
|
||
If you can't set up a proper chroot, <span class="command"><strong>dpkg-depcheck</strong></span> may be of
|
||
assistance (see <a class="xref" href="tools.html#dpkg-depcheck" title="A.6.7. dpkg-depcheck">Section A.6.7, “<span class="command"><strong>dpkg-depcheck</strong></span>”</a>).
|
||
</p><p>
|
||
See the <a class="ulink" href="http://www.debian.org/doc/debian-policy/" target="_top">Debian Policy
|
||
Manual</a> for instructions on setting build dependencies.
|
||
</p></li><li class="listitem"><p>
|
||
Don't set architecture to a value other than <code class="literal">all</code> or
|
||
<code class="literal">any</code> unless you really mean it. In too many cases,
|
||
maintainers don't follow the instructions in the <a class="ulink" href="http://www.debian.org/doc/debian-policy/" target="_top">Debian Policy Manual</a>. Setting your
|
||
architecture to only one architecture (such as <code class="literal">i386</code>
|
||
or <code class="literal">amd64</code>) is usually incorrect.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure your source package is correct. Do <code class="literal">dpkg-source -x
|
||
<em class="replaceable"><code>package</code></em>.dsc</code> to make sure your source
|
||
package unpacks properly. Then, in there, try building your package from
|
||
scratch with <span class="command"><strong>dpkg-buildpackage</strong></span>.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure you don't ship your source package with the
|
||
<code class="filename">debian/files</code> or <code class="filename">debian/substvars</code>
|
||
files. They should be removed by the <code class="literal">clean</code> target of
|
||
<code class="filename">debian/rules</code>.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure you don't rely on locally installed or hacked configurations or
|
||
programs. For instance, you should never be calling programs in
|
||
<code class="filename">/usr/local/bin</code> 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.
|
||
</p></li><li class="listitem"><p>
|
||
Don't depend on the package you're building being installed already (a sub-case
|
||
of the above issue). There are, of course, exceptions to this rule, but be
|
||
aware that any case like this needs manual bootstrapping and cannot be done
|
||
by automated package builders.
|
||
</p></li><li class="listitem"><p>
|
||
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.
|
||
</p></li><li class="listitem"><p>
|
||
Make sure your <code class="filename">debian/rules</code> contains separate <code class="literal">binary-arch</code>
|
||
and <code class="literal">binary-indep</code> 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 <span class="command"><strong>dpkg-buildpackage -B</strong></span>.
|
||
</p></li></ol></div></div><div class="section" title="5.10.2. Guidelines for porter uploads"><div class="titlepage"><div><div><h3 class="title"><a id="porter-guidelines"></a>5.10.2. Guidelines for porter uploads</h3></div></div></div><p>
|
||
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 <a class="xref" href="pkgs.html#nmu-guidelines" title="5.11.1. When and how to do an NMU">Section 5.11.1, “When and how to do an NMU”</a> instead.
|
||
</p><p>
|
||
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
|
||
<code class="filename">debian/changelog</code>.
|
||
</p><p>
|
||
The way to invoke <span class="command"><strong>dpkg-buildpackage</strong></span> is as
|
||
<code class="literal">dpkg-buildpackage -B
|
||
-m<em class="replaceable"><code>porter-email</code></em></code>. Of course, set
|
||
<em class="replaceable"><code>porter-email</code></em> to your email address. This will do a
|
||
binary-only build of only the architecture-dependent portions of the package,
|
||
using the <code class="literal">binary-arch</code> target in
|
||
<code class="filename">debian/rules</code>.
|
||
</p><p>
|
||
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
|
||
<span class="command"><strong>debsign</strong></span> on your <code class="filename">.changes</code> file to have
|
||
it signed conveniently, or use the remote signing mode of
|
||
<span class="command"><strong>dpkg-sig</strong></span>.
|
||
</p><div class="section" title="5.10.2.1. Recompilation or binary-only NMU"><div class="titlepage"><div><div><h4 class="title"><a id="binary-only-nmu"></a>5.10.2.1. Recompilation or binary-only NMU</h4></div></div></div><p>
|
||
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, etc.). 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
|
||
(<span class="command"><strong>dak</strong></span> refuses to install new packages if they don't have a
|
||
version number greater than the currently available one).
|
||
</p><p>
|
||
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 have inter-dependencies
|
||
generated using dpkg's substitution variable <code class="literal">$(Source-Version)</code>.
|
||
</p><p>
|
||
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.
|
||
</p><p>
|
||
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).
|
||
</p><p>
|
||
The ``magic'' for a recompilation-only NMU is triggered by using a suffix
|
||
appended to the package version number, following the form
|
||
<code class="literal">b<em class="replaceable"><code>number</code></em></code>.
|
||
For instance, if the latest version you are recompiling against was version
|
||
<code class="literal">2.9-3</code>, your binary-only NMU should carry a version of
|
||
<code class="literal">2.9-3+b1</code>. If the latest version was <code class="literal">3.4+b1</code>
|
||
(i.e, a native package with a previous recompilation NMU), your
|
||
binary-only NMU should have a version number of <code class="literal">3.4+b2</code>.<sup>[<a id="idp20491832" href="#ftn.idp20491832" class="footnote">4</a>]</sup>
|
||
</p><p>
|
||
Similar to initial porter uploads, the correct way of invoking
|
||
<span class="command"><strong>dpkg-buildpackage</strong></span> is <code class="literal">dpkg-buildpackage -B</code>
|
||
to only build the architecture-dependent parts of the package.
|
||
</p></div><div class="section" title="5.10.2.2. When to do a source NMU if you are a porter"><div class="titlepage"><div><div><h4 class="title"><a id="source-nmu-when-porter"></a>5.10.2.2. When to do a source NMU if you are a porter</h4></div></div></div><p>
|
||
Porters doing a source NMU generally follow the guidelines found in <a class="xref" href="pkgs.html#nmu" title="5.11. Non-Maintainer Uploads (NMUs)">Section 5.11, “Non-Maintainer Uploads (NMUs)”</a>, 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.
|
||
</p><p>
|
||
If you are a porter doing an NMU for <code class="literal">unstable</code>, 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 <code class="literal">unstable</code> 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 <code class="literal">stable</code> or
|
||
<code class="literal">testing</code>, please coordinate with the appropriate release
|
||
team first.
|
||
</p><p>
|
||
Secondly, porters doing source NMUs should make sure that the bug they submit
|
||
to the BTS should be of severity <code class="literal">serious</code> 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 architectures in order to
|
||
comply with many licenses.
|
||
</p><p>
|
||
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 <code class="literal">#ifdef</code> your work properly; also,
|
||
document your kludge so that people know to remove it once the external
|
||
problems have been fixed.
|
||
</p><p>
|
||
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.
|
||
</p></div></div><div class="section" title="5.10.3. Porting infrastructure and automation"><div class="titlepage"><div><div><h3 class="title"><a id="porter-automation"></a>5.10.3. Porting infrastructure and automation</h3></div></div></div><p>
|
||
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.
|
||
</p><div class="section" title="5.10.3.1. Mailing lists and web pages"><div class="titlepage"><div><div><h4 class="title"><a id="s5.10.3.1"></a>5.10.3.1. Mailing lists and web pages</h4></div></div></div><p>
|
||
Web pages containing the status of each port can be found at <a class="ulink" href="http://www.debian.org/ports/" target="_top">http://www.debian.org/ports/</a>.
|
||
</p><p>
|
||
Each port of Debian has a mailing list. The list of porting mailing lists can
|
||
be found at <a class="ulink" href="http://lists.debian.org/ports.html" target="_top">http://lists.debian.org/ports.html</a>. These
|
||
lists are used to coordinate porters, and to connect the users of a given port
|
||
with the porters.
|
||
</p></div><div class="section" title="5.10.3.2. Porter tools"><div class="titlepage"><div><div><h4 class="title"><a id="s5.10.3.2"></a>5.10.3.2. Porter tools</h4></div></div></div><p>
|
||
Descriptions of several porting tools can be found in <a class="xref" href="tools.html#tools-porting" title="A.7. Porting tools">Section A.7, “Porting tools”</a>.
|
||
</p></div><div class="section" title="5.10.3.3. wanna-build"><div class="titlepage"><div><div><h4 class="title"><a id="wanna-build"></a>5.10.3.3. <code class="systemitem">wanna-build</code></h4></div></div></div><p>
|
||
The <code class="systemitem">wanna-build</code> system is used as a
|
||
distributed, client-server build distribution system. It is usually used in
|
||
conjunction with build daemons running the <code class="systemitem">buildd</code>
|
||
program. <code class="literal">Build daemons</code> are ``slave'' hosts
|
||
which contact the central <code class="systemitem">wanna-build</code>
|
||
system to receive a list of packages that need to be built.
|
||
</p><p>
|
||
<code class="systemitem">wanna-build</code> is not yet available as a
|
||
package; however, all Debian porting efforts are using it for automated
|
||
package building. The tool used to do the actual package builds, <code class="systemitem">sbuild</code> is available as a package, see its
|
||
description in <a class="xref" href="tools.html#sbuild" title="A.4.4. sbuild">Section A.4.4, “<code class="systemitem">sbuild</code>”</a>. Please note that the packaged
|
||
version is not the same as the one used on build daemons, but it is close
|
||
enough to reproduce problems.
|
||
</p><p>
|
||
Most of the data produced by <code class="systemitem">wanna-build</code>
|
||
which is generally useful to porters is available on the
|
||
web at <a class="ulink" href="http://buildd.debian.org/" target="_top">http://buildd.debian.org/</a>. This data includes nightly
|
||
updated statistics, queueing information and logs for build attempts.
|
||
</p><p>
|
||
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 <span class="command"><strong>gcc</strong></span> bounds checking). It will
|
||
also enable Debian to recompile entire distributions quickly.
|
||
</p><p>
|
||
The wanna-build team, in charge of the buildds,
|
||
can be reached at <code class="literal">debian-wb-team@lists.debian.org</code>.
|
||
To determine who (wanna-build team, release team) and how (mail, BTS)
|
||
to contact, refer to <a class="ulink" href="http://lists.debian.org/debian-project/2009/03/msg00096.html" target="_top">http://lists.debian.org/debian-project/2009/03/msg00096.html</a>.
|
||
</p><p>
|
||
When requesting binNMUs or give-backs (retries after a failed build),
|
||
please use the format described at <a class="ulink" href="http://release.debian.org/wanna-build.txt" target="_top">http://release.debian.org/wanna-build.txt</a>.
|
||
</p></div></div><div class="section" title="5.10.4. When your package is not portable"><div class="titlepage"><div><div><h3 class="title"><a id="packages-arch-specific"></a>5.10.4. When your package is <span class="emphasis"><em>not</em></span> portable</h3></div></div></div><p>
|
||
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
|
||
available for <code class="literal">i386</code> and <code class="literal">amd64</code>), or uses
|
||
other hardware-specific features not supported on all architectures.
|
||
</p><p>
|
||
In order to prevent broken packages from being uploaded to the archive, and
|
||
wasting buildd time, you need to do a few things:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
First, make sure your package <span class="emphasis"><em>does</em></span> 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.
|
||
</p><p>
|
||
Additionally, if you believe the list of supported architectures is pretty
|
||
constant, you should change <code class="literal">any</code> to a list of supported
|
||
architectures in <code class="filename">debian/control</code>. This way, the build will
|
||
fail also, and indicate this to a human reader without actually trying.
|
||
</p></li><li class="listitem"><p>
|
||
In order to prevent autobuilders from needlessly trying to build your package,
|
||
it must be included in <code class="filename">Packages-arch-specific</code>, a list used
|
||
by the <span class="command"><strong>wanna-build</strong></span> script. The current version is available
|
||
as <a class="ulink" href="http://buildd.debian.org/quinn-diff/Packages-arch-specific" target="_top">http://buildd.debian.org/quinn-diff/Packages-arch-specific</a>;
|
||
please see the top of the file for whom to contact for changes.
|
||
</p></li></ul></div><p>
|
||
Please note that it is insufficient to only add your package to
|
||
<code class="filename">Packages-arch-specific</code> 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 <code class="systemitem">ftp.debian.org</code>.
|
||
</p></div><div class="section" title="5.10.5. Marking non-free packages as auto-buildable"><div class="titlepage"><div><div><h3 class="title"><a id="non-free-buildd"></a>5.10.5. Marking non-free packages as auto-buildable</h3></div></div></div><p>
|
||
By default packages from the <code class="literal">non-free</code> section are not built by the autobuilder
|
||
network (mostly because the license of the packages could disapprove).
|
||
To enable a package to be build you need to perform the following
|
||
steps:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Check whether it is legally allowed and technically possible
|
||
to auto-build the package;
|
||
</p></li><li class="listitem"><p>
|
||
Add <code class="literal">XS-Autobuild: yes</code> into the header part
|
||
of <code class="filename">debian/control</code>;
|
||
</p></li><li class="listitem"><p>
|
||
Send an email to <code class="email"><<a class="email" href="mailto:nonfree@release.debian.org">nonfree@release.debian.org</a>></code> and explain why the
|
||
package can legitimately and technically be auto-built.
|
||
</p></li></ol></div></div></div><div class="section" title="5.11. Non-Maintainer Uploads (NMUs)"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="nmu"></a>5.11. Non-Maintainer Uploads (NMUs)</h2></div></div></div><p>
|
||
Every package has one or more maintainers. Normally, these are the people who
|
||
work on and upload new versions of the package. In some situations, it is
|
||
useful that other developers can upload a new version as well, for example if
|
||
they want to fix a bug in a package they don't maintain, when the maintainer
|
||
needs help to respond to issues. Such uploads are called
|
||
<span class="emphasis"><em>Non-Maintainer Uploads (NMU)</em></span>.
|
||
</p><div class="section" title="5.11.1. When and how to do an NMU"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-guidelines"></a>5.11.1. When and how to do an NMU</h3></div></div></div><p>
|
||
Before doing an NMU, consider the following questions:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
Does your NMU really fix bugs? Fixing cosmetic issues or changing the
|
||
packaging style in NMUs is discouraged.
|
||
</p></li><li class="listitem"><p>
|
||
Did you give enough time to the maintainer? When was the bug reported to the
|
||
BTS? Being busy for a week or two isn't unusual. Is the bug so severe that it
|
||
needs to be fixed right now, or can it wait a few more days?
|
||
</p></li><li class="listitem"><p>
|
||
How confident are you about your changes? 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. If you are not 100% sure of what you did, it might be a good idea
|
||
to seek advice from others. Remember that if you break something in your NMU,
|
||
many people will be very unhappy about it.
|
||
</p></li><li class="listitem"><p>
|
||
Have you clearly expressed your intention to NMU, at least in the BTS?
|
||
It is also a good idea to try to contact the
|
||
maintainer by other means (private email, IRC).
|
||
</p></li><li class="listitem"><p>
|
||
If the maintainer is usually active and responsive, have you tried to contact
|
||
him? In general it should be considered preferable that a maintainer takes care
|
||
of an issue himself and that he is given the chance to review and correct your
|
||
patch, because he can be expected to be more aware of potential issues which an
|
||
NMUer might miss. It is often a better use of everyone's time if the maintainer
|
||
is given an opportunity to upload a fix on their own.
|
||
</p></li></ul></div><p>
|
||
When doing an NMU, you must first make sure that your intention to NMU is
|
||
clear. Then, you must send a patch with the differences between the
|
||
current package and your proposed NMU to the BTS. The
|
||
<span class="command"><strong>nmudiff</strong></span> script in the <code class="systemitem">devscripts</code> package
|
||
might be helpful.
|
||
</p><p>
|
||
While preparing the patch, you should better be aware of any package-specific
|
||
practices that the maintainer might be using. Taking them into account
|
||
reduces the burden of integrating your changes into the normal package
|
||
workflow and thus increases the chances that integration will happen. A good
|
||
place where to look for for possible package-specific practices is
|
||
<a class="ulink" href="http://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource" target="_top"><code class="filename">debian/README.source</code></a>.
|
||
</p><p>
|
||
Unless you have an excellent reason not to do so, you must then give some time
|
||
to the maintainer to react (for example, by uploading to the
|
||
<code class="literal">DELAYED</code> queue). Here are some recommended values to use for delays:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
Upload fixing only release-critical bugs older than 7 days, with no maintainer activity on the bug for 7 days and no indication that a fix is in progress: 0 days
|
||
</p></li><li class="listitem"><p>
|
||
Upload fixing only release-critical bugs older than 7 days: 2 days
|
||
</p></li><li class="listitem"><p>
|
||
Upload fixing only release-critical and important bugs: 5 days
|
||
</p></li><li class="listitem"><p>
|
||
Other NMUs: 10 days
|
||
</p></li></ul></div><p>
|
||
Those delays are only examples. In some cases, such as uploads fixing security
|
||
issues, or fixes for trivial bugs that blocking a transition, it is desirable
|
||
that the fixed package reaches <code class="literal">unstable</code> sooner.
|
||
</p><p>
|
||
Sometimes, release managers decide to allow NMUs with shorter delays for a
|
||
subset of bugs (e.g release-critical bugs older than 7 days). Also, some
|
||
maintainers list themselves in the <a class="ulink" href="http://wiki.debian.org/LowThresholdNmu" target="_top">Low
|
||
Threshold NMU list</a>, and accept that NMUs are uploaded without delay. But
|
||
even in those cases, it's still a good idea to give the maintainer a few days
|
||
to react before you upload, especially if the patch wasn't available in the BTS
|
||
before, or if you know that the maintainer is generally active.
|
||
</p><p>
|
||
After you upload an NMU, you are responsible for the possible problems that you
|
||
might have introduced. You must keep an eye on the package (subscribing to the
|
||
package on the PTS is a good way to achieve this).
|
||
</p><p>
|
||
This is not a license to perform NMUs thoughtlessly. If you NMU when it is
|
||
clear that the maintainers are active and would have acknowledged a patch in a
|
||
timely manner, or if you ignore the recommendations of this document, your
|
||
upload might be a cause of conflict with the maintainer.
|
||
You should always be prepared to
|
||
defend the wisdom of any NMU you perform on its own merits.
|
||
</p></div><div class="section" title="5.11.2. NMUs and debian/changelog"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-changelog"></a>5.11.2. NMUs and <code class="filename">debian/changelog</code></h3></div></div></div><p>
|
||
Just like any other (source) upload, NMUs must add an entry to
|
||
<code class="filename">debian/changelog</code>, telling what has changed with this
|
||
upload. The first line of this entry must explicitely mention that this upload is an NMU, e.g.:
|
||
</p><pre class="screen">
|
||
* Non-maintainer upload.
|
||
</pre><p>
|
||
The way to version NMUs differs for native and non-native packages.
|
||
</p><p>
|
||
If the package is a native package (without a Debian revision in the version number),
|
||
the version must be the version of the last maintainer upload, plus
|
||
<code class="literal">+nmu<em class="replaceable"><code>X</code></em></code>, where
|
||
<em class="replaceable"><code>X</code></em> is a counter starting at <code class="literal">1</code>.
|
||
If
|
||
the last upload was also an NMU, the counter should be increased. For example,
|
||
if the current version is <code class="literal">1.5</code>, then an NMU would get
|
||
version <code class="literal">1.5+nmu1</code>.
|
||
</p><p>
|
||
If the package is not a native package, you should add a minor version number
|
||
to the Debian revision part of the version number (the portion after the last
|
||
hyphen). This extra number must start at <code class="literal">1</code>. For example,
|
||
if the current version is <code class="literal">1.5-2</code>, then an NMU would get
|
||
version <code class="literal">1.5-2.1</code>. If a new upstream version
|
||
is packaged in the NMU, the Debian revision is set to <code class="literal">0</code>, for
|
||
example <code class="literal">1.6-0.1</code>.
|
||
</p><p>
|
||
In both cases, if the last upload was also an NMU, the counter should
|
||
be increased. For example, if the current version is
|
||
<code class="literal">1.5+nmu3</code> (a native package which has already been
|
||
NMUed), the NMU would get version <code class="literal">1.5+nmu4</code>.
|
||
</p><p>
|
||
A special versioning scheme is needed to avoid disrupting the maintainer's
|
||
work, since using an integer for the Debian revision will potentially
|
||
conflict with a maintainer upload already in preparation at the time of an
|
||
NMU, or even one sitting in the ftp NEW queue.
|
||
It also has the
|
||
benefit of making it visually clear that a package in the archive was not made
|
||
by the official maintainer.
|
||
</p><p>
|
||
If you upload a package to testing or stable, you sometimes need to "fork" the
|
||
version number tree. This is the case for security uploads, for example. For
|
||
this, a version of the form
|
||
<code class="literal">+deb<em class="replaceable"><code>XY</code></em>u<em class="replaceable"><code>Z</code></em></code>
|
||
should be used, where <em class="replaceable"><code>X</code></em> and
|
||
<em class="replaceable"><code>Y</code></em> are the major and minor release numbers, and
|
||
<em class="replaceable"><code>Z</code></em> is a counter starting at <code class="literal">1</code>.
|
||
When the release number is not yet known (often the case for
|
||
<code class="literal">testing</code>, at the beginning of release cycles), the lowest
|
||
release number higher than the last stable release number must be used. For
|
||
example, while Lenny (Debian 5.0) is stable, a security NMU to stable for a
|
||
package at version <code class="literal">1.5-3</code> would have version
|
||
<code class="literal">1.5-3+deb50u1</code>, whereas a security NMU to Squeeze would get
|
||
version <code class="literal">1.5-3+deb60u1</code>. After the release of Squeeze, security
|
||
uploads to the <code class="literal">testing</code> distribution will be versioned
|
||
<code class="literal">+deb61uZ</code>, until it is known whether that release will be
|
||
Debian 6.1 or Debian 7.0 (if that becomes the case, uploads will be versioned
|
||
as <code class="literal">+deb70uZ</code>).
|
||
</p></div><div class="section" title="5.11.3. Using the DELAYED/ queue"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-delayed"></a>5.11.3. Using the <code class="literal">DELAYED/</code> queue</h3></div></div></div><p>
|
||
Having to wait for a response after you request permission to NMU is
|
||
inefficient, because it costs the NMUer a context switch to come back to the
|
||
issue.
|
||
The <code class="literal">DELAYED</code> queue (see <a class="xref" href="pkgs.html#delayed-incoming" title="5.6.2. Delayed uploads">Section 5.6.2, “Delayed uploads”</a>)
|
||
allows the developer doing the NMU to perform all the necessary tasks at the
|
||
same time. For instance, instead of telling the maintainer that you will
|
||
upload the updated
|
||
package in 7 days, you should upload the package to
|
||
<code class="literal">DELAYED/7</code> and tell the maintainer that he has 7 days to
|
||
react. During this time, the maintainer can ask you to delay the upload some
|
||
more, or cancel your upload.
|
||
</p><p>
|
||
The <code class="literal">DELAYED</code> queue should not be used to put additional
|
||
pressure on the maintainer. In particular, it's important that you are
|
||
available to cancel or delay the upload before the delay expires since the
|
||
maintainer cannot cancel the upload himself.
|
||
</p><p>
|
||
If you make an NMU to <code class="literal">DELAYED</code> and the maintainer updates
|
||
his package before the delay expires, your upload will be rejected because a
|
||
newer version is already available in the archive.
|
||
Ideally, the maintainer will take care to include your proposed changes (or
|
||
at least a solution for the problems they address) in that upload.
|
||
</p></div><div class="section" title="5.11.4. NMUs from the maintainer's point of view"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-maintainer"></a>5.11.4. NMUs from the maintainer's point of view</h3></div></div></div><p>
|
||
When someone NMUs your package, this means they want to help you to keep it in
|
||
good shape. This gives users fixed packages faster. You
|
||
can consider asking the NMUer to become a co-maintainer of the package.
|
||
Receiving an NMU on a package is not a bad
|
||
thing; it just means that the package is interesting enough for other people to
|
||
work on it.
|
||
</p><p>
|
||
To acknowledge an NMU, include its changes and changelog entry in your next
|
||
maintainer upload. If you do not acknowledge the NMU by including the
|
||
NMU changelog entry in your changelog, the bugs will remain closed in the
|
||
BTS but will be listed as affecting your maintainer version of the package.
|
||
</p></div><div class="section" title="5.11.5. Source NMUs vs Binary-only NMUs (binNMUs)"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-binnmu"></a>5.11.5. Source NMUs vs Binary-only NMUs (binNMUs)</h3></div></div></div><p>
|
||
The full name of an NMU is <span class="emphasis"><em>source NMU</em></span>. There is also
|
||
another type, namely the <span class="emphasis"><em>binary-only NMU</em></span>, or
|
||
<span class="emphasis"><em>binNMU</em></span>. A binNMU is also a package upload by someone
|
||
other than the package's maintainer. However, it is a binary-only upload.
|
||
</p><p>
|
||
When a library (or other dependency) is updated, the packages using it may need
|
||
to be rebuilt. Since no changes to the source are needed, the same source
|
||
package is used.
|
||
</p><p>
|
||
BinNMUs are usually triggered on the buildds by wanna-build.
|
||
An entry is added to <code class="filename">debian/changelog</code>,
|
||
explaining why the upload was needed and increasing the version number as
|
||
described in <a class="xref" href="pkgs.html#binary-only-nmu" title="5.10.2.1. Recompilation or binary-only NMU">Section 5.10.2.1, “Recompilation or binary-only NMU”</a>.
|
||
This entry should not be included in the next upload.
|
||
</p><p>
|
||
Buildds upload packages for their architecture to the archive as binary-only
|
||
uploads. Strictly speaking, these are binNMUs. However, they are not normally
|
||
called NMU, and they don't add an entry to <code class="filename">debian/changelog</code>.
|
||
</p></div><div class="section" title="5.11.6. NMUs vs QA uploads"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-qa-upload"></a>5.11.6. NMUs vs QA uploads</h3></div></div></div><p>
|
||
NMUs are uploads of packages by somebody else than their assigned maintainer.
|
||
There is
|
||
another type of upload where the uploaded package is not yours: QA uploads. QA
|
||
uploads are uploads of orphaned packages.
|
||
</p><p>
|
||
QA uploads are very much like normal maintainer uploads: they may fix anything,
|
||
even minor issues; the version numbering is normal, and there is no need to use
|
||
a delayed upload. The difference is that you are not listed as the <code class="literal">Maintainer</code>
|
||
or <code class="literal">Uploader</code> for the package. Also, the changelog entry of a QA upload has a
|
||
special first line:
|
||
</p><pre class="screen">
|
||
* QA upload.
|
||
</pre><p>
|
||
If you want to do an NMU, and it seems that the maintainer is not active, it is
|
||
wise to check if the package is orphaned
|
||
(this information is displayed on the package's Package Tracking System page).
|
||
When doing the first QA upload to an
|
||
orphaned package, the maintainer should be set to <code class="literal">Debian QA Group
|
||
<packages@qa.debian.org></code>. Orphaned packages which did
|
||
not yet have a QA upload still have their old maintainer set. There is a list
|
||
of them at <a class="ulink" href="http://qa.debian.org/orphaned.html" target="_top">http://qa.debian.org/orphaned.html</a>.
|
||
</p><p>
|
||
Instead of doing a QA upload, you can also consider adopting the package by
|
||
making yourself the maintainer. You don't need permission from anybody to
|
||
adopt an orphaned package, you can just set yourself as maintainer and upload
|
||
the new version (see <a class="xref" href="pkgs.html#adopting" title="5.9.5. Adopting a package">Section 5.9.5, “Adopting a package”</a>).
|
||
</p></div><div class="section" title="5.11.7. NMUs vs team uploads"><div class="titlepage"><div><div><h3 class="title"><a id="nmu-team-upload"></a>5.11.7. NMUs vs team uploads</h3></div></div></div><p>
|
||
Sometimes you are fixing and/or updating a package because you are member of a
|
||
packaging team (which uses a mailing list as <code class="literal">Maintainer</code> or <code class="literal">Uploader</code>, see <a class="xref" href="pkgs.html#collaborative-maint" title="5.12. Collaborative maintenance">Section 5.12, “Collaborative maintenance”</a>) but you don't want to add yourself to <code class="literal">Uploaders</code>
|
||
because you do not plan to contribute regularly to this specific package. If it
|
||
conforms with your team's policy, you can perform a normal upload without
|
||
being listed directly as <code class="literal">Maintainer</code> or <code class="literal">Uploader</code>. In that case, you should
|
||
start your changelog entry with the following line:
|
||
</p><pre class="screen">
|
||
* Team upload.
|
||
</pre></div></div><div class="section" title="5.12. Collaborative maintenance"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="collaborative-maint"></a>5.12. Collaborative maintenance</h2></div></div></div><p>
|
||
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
|
||
<code class="literal">standard</code> or which are part of the base set have
|
||
co-maintainers.
|
||
</p><p>
|
||
Generally there is a primary maintainer and one or more co-maintainers. The
|
||
primary maintainer is the person whose name is listed in the
|
||
<code class="literal">Maintainer</code> field of the <code class="filename">debian/control</code>
|
||
file. Co-maintainers are all the other maintainers,
|
||
usually listed in the <code class="literal">Uploaders</code> field of the
|
||
<code class="filename">debian/control</code> file.
|
||
</p><p>
|
||
In its most basic form, the process of adding a new co-maintainer is quite
|
||
easy:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
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 <code class="literal">CVS</code> or <code class="literal">Subversion</code>. Alioth (see
|
||
<a class="xref" href="resources.html#alioth" title="4.12. Debian's FusionForge installation: Alioth">Section 4.12, “Debian's FusionForge installation: Alioth”</a>) provides such tools, amongst others.
|
||
</p></li><li class="listitem"><p>
|
||
Add the co-maintainer's correct maintainer name and address to the
|
||
<code class="literal">Uploaders</code> field in the first paragraph of the
|
||
<code class="filename">debian/control</code> file.
|
||
</p><pre class="screen">
|
||
Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>
|
||
</pre></li><li class="listitem"><p>
|
||
Using the PTS (<a class="xref" href="resources.html#pkg-tracking-system" title="4.10. The Package Tracking System">Section 4.10, “The Package Tracking System”</a>), the co-maintainers
|
||
should subscribe themselves to the appropriate source package.
|
||
</p></li></ul></div><p>
|
||
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 <code class="literal">Maintainer</code> and <code class="literal">Uploaders</code> field of each package must be
|
||
managed with care. It is recommended to choose between one of the two
|
||
following schemes:
|
||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
||
Put the team member mainly responsible for the package in the <code class="literal">Maintainer</code> field.
|
||
In the <code class="literal">Uploaders</code>, put the mailing list address, and the team members who care
|
||
for the package.
|
||
</p></li><li class="listitem"><p>
|
||
Put the mailing list address in the <code class="literal">Maintainer</code> field. In the <code class="literal">Uploaders</code> 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).
|
||
</p></li></ol></div><p>
|
||
In any case, it is a bad idea to automatically put all team members in the
|
||
<code class="literal">Uploaders</code> field. It clutters the Developer's Package Overview listing (see
|
||
<a class="xref" href="resources.html#ddpo" title="4.11. Developer's packages overview">Section 4.11, “Developer's packages overview”</a>) with packages one doesn't really care for, and creates
|
||
a false sense of good maintenance. For the same reason, team members do
|
||
not need to add themselves to the <code class="literal">Uploaders</code> field just because they are
|
||
uploading the package once, they can do a “Team upload” (see <a class="xref" href="pkgs.html#nmu-team-upload" title="5.11.7. NMUs vs team uploads">Section 5.11.7, “NMUs vs team uploads”</a>). Conversely, it is a bad idea to keep a
|
||
package with only the mailing list address as a <code class="literal">Maintainer</code> and no
|
||
<code class="literal">Uploaders</code>.
|
||
</p></div><div class="section" title="5.13. The testing distribution"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="testing"></a>5.13. The testing distribution</h2></div></div></div><div class="section" title="5.13.1. Basics"><div class="titlepage"><div><div><h3 class="title"><a id="testing-basics"></a>5.13.1. Basics</h3></div></div></div><p>
|
||
Packages are usually installed into the <code class="literal">testing</code> distribution
|
||
after they have undergone some degree of <code class="literal">testing</code> in
|
||
<code class="literal">unstable</code>.
|
||
</p><p>
|
||
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 <code class="literal">testing</code>.
|
||
This way, <code class="literal">testing</code> should always be close to
|
||
being a release candidate. Please see below for details.
|
||
</p></div><div class="section" title="5.13.2. Updates from unstable"><div class="titlepage"><div><div><h3 class="title"><a id="testing-unstable"></a>5.13.2. Updates from unstable</h3></div></div></div><p>
|
||
The scripts that update the <code class="literal">testing</code> distribution are run
|
||
twice each day, right after the installation of the updated packages; these
|
||
scripts are called <code class="literal">britney</code>. They generate the
|
||
<code class="filename">Packages</code> files for the <code class="literal">testing</code>
|
||
distribution, but they do so in an intelligent manner; they try to avoid any
|
||
inconsistency and to use only non-buggy packages.
|
||
</p><p>
|
||
The inclusion of a package from <code class="literal">unstable</code> is conditional on
|
||
the following:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
The package must have been available in <code class="literal">unstable</code> 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 <code class="literal">testing</code> transition is taken into account. Those
|
||
delays may be doubled during a freeze, or <code class="literal">testing</code>
|
||
transitions may be switched off altogether;
|
||
</p></li><li class="listitem"><p>
|
||
It must not have new release-critical bugs (RC bugs affecting the version
|
||
available in <code class="literal">unstable</code>, but not affecting the version in
|
||
<code class="literal">testing</code>);
|
||
</p></li><li class="listitem"><p>
|
||
It must be available on all architectures on which it has previously been built
|
||
in <code class="literal">unstable</code>. <a class="link" href="resources.html#dak-ls" title="4.9.2. The dak ls utility">dak ls</a> may be of interest
|
||
to check that information;
|
||
</p></li><li class="listitem"><p>
|
||
It must not break any dependency of a package which is already available in
|
||
<code class="literal">testing</code>;
|
||
</p></li><li class="listitem"><p>
|
||
The packages on which it depends must either be available in
|
||
<code class="literal">testing</code> or they must be accepted into
|
||
<code class="literal">testing</code> at the same time (and they will be if they fulfill
|
||
all the necessary criteria).
|
||
</p></li></ul></div><p>
|
||
To find out whether a package is progressing into <code class="literal">testing</code>
|
||
or not, see the <code class="literal">testing</code> script output on the <a class="ulink" href="http://www.debian.org/devel/testing" target="_top">web page of the testing
|
||
distribution</a>, or use the program <span class="command"><strong>grep-excuses</strong></span> which
|
||
is in the <code class="systemitem">devscripts</code> package. This
|
||
utility can easily be used in a <span class="citerefentry"><span class="refentrytitle">crontab</span>(5)</span>
|
||
to keep yourself informed of the progression of your packages into
|
||
<code class="literal">testing</code>.
|
||
</p><p>
|
||
The <code class="filename">update_excuses</code> 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 <a class="ulink" href="http://www.debian.org/devel/testing" target="_top">testing web page</a> gives some
|
||
more information about the usual problems which may be causing such troubles.
|
||
</p><p>
|
||
Sometimes, some packages never enter <code class="literal">testing</code> because the
|
||
set of interrelationship is too complicated and cannot be sorted out by the
|
||
scripts. See below for details.
|
||
</p><p>
|
||
Some further dependency analysis is shown on <a class="ulink" href="http://release.debian.org/migration/" target="_top">http://release.debian.org/migration/</a> — but be warned, this page also
|
||
shows build dependencies which are not considered by britney.
|
||
</p><div class="section" title="5.13.2.1. Out-of-date"><div class="titlepage"><div><div><h4 class="title"><a id="outdated"></a>5.13.2.1. Out-of-date</h4></div></div></div><p>
|
||
|
||
For the <code class="literal">testing</code> migration script, outdated means: There are
|
||
different versions in <code class="literal">unstable</code> for the release architectures
|
||
(except for the architectures in fuckedarches; fuckedarches is a list of
|
||
architectures that don't keep up (in <code class="filename">update_out.py</code>), but
|
||
currently, it's empty). outdated has nothing whatsoever to do with the
|
||
architectures this package has in <code class="literal">testing</code>.
|
||
</p><p>
|
||
Consider this example:
|
||
</p><div class="informaltable"><table width="100%" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th> </th><th>alpha</th><th>arm</th></tr></thead><tbody><tr><td>testing</td><td>1</td><td>-</td></tr><tr><td>unstable</td><td>1</td><td>2</td></tr></tbody></table></div><p>
|
||
The package is out of date on <code class="literal">alpha</code> in <code class="literal">unstable</code>, and will
|
||
not go to <code class="literal">testing</code>. Removing the package would not help at all, the
|
||
package is still out of date on <code class="literal">alpha</code>, and will not
|
||
propagate to <code class="literal">testing</code>.
|
||
</p><p>
|
||
However, if ftp-master removes a package in <code class="literal">unstable</code> (here
|
||
on <code class="literal">arm</code>):
|
||
</p><div class="informaltable"><table width="100%" border="1"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th> </th><th>alpha</th><th>arm</th><th>hurd-i386</th></tr></thead><tbody><tr><td>testing</td><td>1</td><td>1</td><td>-</td></tr><tr><td>unstable</td><td>2</td><td>-</td><td>1</td></tr></tbody></table></div><p>
|
||
In this case, the package is up to date on all release architectures in
|
||
<code class="literal">unstable</code> (and the extra <code class="literal">hurd-i386</code>
|
||
doesn't matter, as it's not a release architecture).
|
||
</p><p>
|
||
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.)
|
||
</p></div><div class="section" title="5.13.2.2. Removals from testing"><div class="titlepage"><div><div><h4 class="title"><a id="removals"></a>5.13.2.2. Removals from testing</h4></div></div></div><p>
|
||
Sometimes, a package is removed to allow another package in: This happens only
|
||
to allow <span class="emphasis"><em>another</em></span> package to go in if it's ready in every
|
||
other sense. Suppose e.g. that <code class="literal">a</code> cannot be installed
|
||
with the new version of <code class="literal">b</code>; then <code class="literal">a</code> may
|
||
be removed to allow <code class="literal">b</code> in.
|
||
</p><p>
|
||
Of course, there is another reason to remove a package from <code class="literal">testing</code>:
|
||
It's just too buggy (and having a single RC-bug is enough to be
|
||
in this state).
|
||
</p><p>
|
||
Furthermore, if a package has been removed from <code class="literal">unstable</code>,
|
||
and no package in <code class="literal">testing</code> depends on it any more, then it
|
||
will automatically be removed.
|
||
</p></div><div class="section" title="5.13.2.3. Circular dependencies"><div class="titlepage"><div><div><h4 class="title"><a id="circular"></a>5.13.2.3. Circular dependencies</h4></div></div></div><p>
|
||
A situation which is not handled very well by britney is if package
|
||
<code class="literal">a</code> depends on the new version of package
|
||
<code class="literal">b</code>, and vice versa.
|
||
</p><p>
|
||
An example of this is:
|
||
</p><div class="informaltable"><table width="100%" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th> </th><th>testing</th><th>unstable</th></tr></thead><tbody><tr><td>a</td><td>1; depends: b=1</td><td>2; depends: b=2</td></tr><tr><td>b</td><td>1; depends: a=1</td><td>2; depends: a=2</td></tr></tbody></table></div><p>
|
||
Neither package <code class="literal">a</code> nor package <code class="literal">b</code> is
|
||
considered for update.
|
||
</p><p>
|
||
Currently, this requires some manual hinting from the release team. Please
|
||
contact them by sending mail to <code class="email"><<a class="email" href="mailto:debian-release@lists.debian.org">debian-release@lists.debian.org</a>></code> if this
|
||
happens to one of your packages.
|
||
</p></div><div class="section" title="5.13.2.4. Influence of package in testing"><div class="titlepage"><div><div><h4 class="title"><a id="s5.13.2.4"></a>5.13.2.4. Influence of package in testing</h4></div></div></div><p>
|
||
Generally, there is nothing that the status of a package in <code class="literal">testing</code>
|
||
means for transition of the next version from <code class="literal">unstable</code>
|
||
to <code class="literal">testing</code>, 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
|
||
<code class="literal">testing</code> 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 <code class="literal">unstable</code>
|
||
at all during the <code class="literal">testing</code> migration.
|
||
</p><p>
|
||
In summary this means: The only influence that a package being in
|
||
<code class="literal">testing</code> has on a new version of the same package is that the new
|
||
version might go in easier.
|
||
</p></div><div class="section" title="5.13.2.5. Details"><div class="titlepage"><div><div><h4 class="title"><a id="details"></a>5.13.2.5. Details</h4></div></div></div><p>
|
||
If you are interested in details, this is how britney works:
|
||
</p><p>
|
||
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.)
|
||
</p><p>
|
||
Now, the more complex part happens: Britney tries to update <code class="literal">testing</code>
|
||
with the valid candidates. For that, britney tries to add each
|
||
valid candidate to the testing distribution. If the number of uninstallable
|
||
packages in <code class="literal">testing</code> doesn't increase, the package is
|
||
accepted. From that point on, the accepted package is considered to be part
|
||
of <code class="literal">testing</code>, such that all subsequent installability
|
||
tests include this package. Hints from the release team are processed
|
||
before or after this main run, depending on the exact type.
|
||
</p><p>
|
||
If you want to see more details, you can look it up on <a class="ulink" href="http://ftp-master.debian.org/testing/update_output/" target="_top">http://ftp-master.debian.org/testing/update_output/</a>.
|
||
</p><p>
|
||
The hints are available via <a class="ulink" href="http://ftp-master.debian.org/testing/hints/" target="_top">http://ftp-master.debian.org/testing/hints/</a>.
|
||
</p></div></div><div class="section" title="5.13.3. Direct updates to testing"><div class="titlepage"><div><div><h3 class="title"><a id="t-p-u"></a>5.13.3. Direct updates to testing</h3></div></div></div><p>
|
||
The <code class="literal">testing</code> distribution is fed with packages from
|
||
<code class="literal">unstable</code> according to the rules explained above. However,
|
||
in some cases, it is necessary to upload packages built only for
|
||
<code class="literal">testing</code>. For that, you may want to upload to
|
||
<code class="literal">testing-proposed-updates</code>.
|
||
</p><p>
|
||
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 <code class="email"><<a class="email" href="mailto:debian-devel-announce@lists.debian.org">debian-devel-announce@lists.debian.org</a>></code>.
|
||
</p><p>
|
||
You should not upload to <code class="literal">testing-proposed-updates</code> when you
|
||
can update your packages through <code class="literal">unstable</code>. If you can't
|
||
(for example because you have a newer development version in <code class="literal">unstable</code>),
|
||
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 <code class="literal">unstable</code> are possible, if the upload via
|
||
<code class="literal">unstable</code> does not pull in any new dependencies.
|
||
</p><p>
|
||
Version numbers are usually selected by adding the codename of the
|
||
<code class="literal">testing</code> distribution and a running number, like
|
||
<code class="literal">1.2squeeze1</code> for the first upload through
|
||
<code class="literal">testing-proposed-updates</code> of package version
|
||
<code class="literal">1.2</code>.
|
||
</p><p>
|
||
Please make sure you didn't miss any of these items in your upload:
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
|
||
Make sure that your package really needs to go through
|
||
<code class="literal">testing-proposed-updates</code>, and can't go through
|
||
<code class="literal">unstable</code>;
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that you included only the minimal amount of changes;
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that you included an appropriate explanation in the changelog;
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that you've written <code class="literal">testing</code> or
|
||
<code class="literal">testing-proposed-updates</code> into your target distribution;
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that you've built and tested your package in
|
||
<code class="literal">testing</code>, not in <code class="literal">unstable</code>;
|
||
</p></li><li class="listitem"><p>
|
||
Make sure that your version number is higher than the version in
|
||
<code class="literal">testing</code> and <code class="literal">testing-proposed-updates</code>,
|
||
and lower than in <code class="literal">unstable</code>;
|
||
</p></li><li class="listitem"><p>
|
||
After uploading and successful build on all platforms, contact the release team
|
||
at <code class="email"><<a class="email" href="mailto:debian-release@lists.debian.org">debian-release@lists.debian.org</a>></code> and ask them to approve your upload.
|
||
</p></li></ul></div></div><div class="section" title="5.13.4. Frequently asked questions"><div class="titlepage"><div><div><h3 class="title"><a id="faq"></a>5.13.4. Frequently asked questions</h3></div></div></div><div class="section" title="5.13.4.1. What are release-critical bugs, and how do they get counted?"><div class="titlepage"><div><div><h4 class="title"><a id="rc"></a>5.13.4.1. What are release-critical bugs, and how do they get counted?</h4></div></div></div><p>
|
||
All bugs of some higher severities are by default considered release-critical;
|
||
currently, these are <code class="literal">critical</code>, <code class="literal">grave</code> and
|
||
<code class="literal">serious</code> bugs.
|
||
</p><p>
|
||
Such bugs are presumed to have an impact on the chances that the package will
|
||
be released with the <code class="literal">stable</code> release of Debian: in general,
|
||
if a package has open release-critical bugs filed on it, it won't get into
|
||
<code class="literal">testing</code>, and consequently won't be released in
|
||
<code class="literal">stable</code>.
|
||
</p><p>
|
||
The <code class="literal">unstable</code> bug count are all release-critical bugs which
|
||
are marked to apply to <em class="replaceable"><code>package</code></em>/<em class="replaceable"><code>version</code></em>
|
||
combinations that are available in unstable for a release
|
||
architecture. The <code class="literal">testing</code> bug count is defined analogously.
|
||
</p></div><div class="section" title="5.13.4.2. How could installing a package into testing possibly break other packages?"><div class="titlepage"><div><div><h4 class="title"><a id="s5.13.4.2"></a>5.13.4.2. How could installing a package into <code class="literal">testing</code> possibly
|
||
break other packages?</h4></div></div></div><p>
|
||
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 <code class="literal">acmefoo</code> is installed into <code class="literal">testing</code>,
|
||
along with its binary packages <code class="literal">acme-foo-bin</code>,
|
||
<code class="literal">acme-bar-bin</code>, <code class="literal">libacme-foo1</code> and
|
||
<code class="literal">libacme-foo-dev</code>, the old version is removed.
|
||
</p><p>
|
||
However, the old version may have provided a binary package with an old soname
|
||
of a library, such as <code class="literal">libacme-foo0</code>. Removing the old
|
||
<code class="literal">acmefoo</code> will remove <code class="literal">libacme-foo0</code>, which
|
||
will break any packages which depend on it.
|
||
</p><p>
|
||
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 ==, <=, or << varieties.
|
||
</p><p>
|
||
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 <code class="literal">testing</code> breaks all the packages that depended on
|
||
it in <code class="literal">testing</code>,
|
||
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.
|
||
</p><p>
|
||
If you are having problems with complicated groups of packages like this,
|
||
contact <code class="email"><<a class="email" href="mailto:debian-devel@lists.debian.org">debian-devel@lists.debian.org</a>></code> or <code class="email"><<a class="email" href="mailto:debian-release@lists.debian.org">debian-release@lists.debian.org</a>></code> for help.
|
||
</p></div></div></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.idp20423976" href="#idp20423976" class="para">3</a>] </sup> See the <a class="ulink" href="http://www.debian.org/doc/debian-policy/" target="_top">Debian Policy Manual</a> for
|
||
guidelines on what section a package belongs in. </p></div><div class="footnote"><p><sup>[<a id="ftn.idp20491832" href="#idp20491832" class="para">4</a>] </sup>
|
||
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.
|
||
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="resources.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="best-pkging-practices.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 4. Resources for Debian Developers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 6. Best Packaging Practices</td></tr></table></div></body></html>
|