<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.122 $">
+ <!entity cvs-rev "$Revision: 1.128 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
keeping your entry the developer database up-to-date, see <ref
id="user-maint">. Part of this information is also available through
the finger service on Debian servers, try
-<prgn>finger yourlogin@debian.org</prgn> to see what it reports.
-
+<prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.
+ <p>
+This database lets you register some other information like public SSH
+keys that will be automatically installed on the official debian machines
+or like *.debian.net DNS entry. Those features are documented
+here : <url id="&url-debian-db-mail-gw;">
<sect id="servers-mirrors">Mirrors of Debian servers
<p>
that newer push mirroring techniques ensure that mirrors are as
up-to-date as they can be.
<p>
-The main web page listing the available public FTP (and, usually,
-HTTP) servers can be found at <url id="&url-debian-mirrors;">. More
+The main web page listing the available public FTP/HTTP
+servers can be found at <url id="&url-debian-mirrors;">. More
information concerning Debian mirrors can be found at <url
id="&url-debian-mirroring;">. This useful page includes information
and tools which can be helpful if you are interested in setting up
to make sure everything in this distribution is working properly, it is
sometimes literally unstable.
<p>
-The testing distribution is generated automatically by taking
+<ref id="testing"> is generated automatically by taking
packages from unstable if they satisfy certain criteria. Those
criteria should ensure a good quality for packages within testing.
-<ref id="testing-scripts"> are launched each day after the
+The update to testing is launched each day after the
new packages have been installed.
<p>
After a period of development, once the release manager deems fit, the
<em>testing</em> distribution is frozen, meaning that the policies
-which control how packages move from <em>unstable</em> to testing are
+which control how packages move from <em>unstable</em> to <em>testing</em> are
tightened. Packages which are too buggy are removed. No changes are
allowed into <em>testing</em> except for bug fixes. After some time
has elapsed, depending on progress, the <em>testing</em> distribution
easily upload a package in one of the delayed directories:
<example>DELAY=5 dupload --to delayed <changes-file></example>
- <sect id="testing-scripts">
- <heading>The testing scripts</heading>
+ <sect id="testing">
+ <heading>The "testing" distribution</heading>
<p>
-The testing scripts are run each day after the installation of the
+The scripts that update the <em>testing</em> distribution are run each day
+after the installation of the
updated packages. They generate the <file>Packages</file> files for
the <em>testing</em> distribution, but they do so in an intelligent manner
trying to avoid any inconsistency and trying to use only
id="&url-testing-maint;">. Alternatively, it is possible to use
the <prgn>grep-excuses</prgn> program part of the
<package>devscripts</package> package. It can be easily put in a crontab
-to keep someone informed of the progression of his packages in testing.
+to keep someone informed of the progression of his packages in <em>testing</em>.
<p>
The <file>update_excuses</file> file does not always give the precise reason
why the package is refused, one may have to find it on their own by looking
id="&url-testing-faq;" name="testing FAQ"> gives some more information
about the usual problems which may be causing such troubles.
<p>
-Sometimes, some packages never enter testing because the set of
+Sometimes, some packages never enter <em>testing</em> because the set of
inter-relationship is too complicated and can not be sorted out
by the scripts. In that case, the release manager must be
contacted, and he will force the inclusion of the packages.
libdbd-mysql-perl | 1.2219-1 | unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
</example>
<p>
-In this example, you can see that the version in unstable differs from
-the version in testing and that there has been a binary-only NMU of the
+In this example, you can see that the version in <em>unstable</em> differs from
+the version in <em>testing</em> and that there has been a binary-only NMU of the
package for the alpha architecture. Each time the package has been
recompiled on most of the architectures.
<item>
In the future, you may receive regular summary mails to keep you
informed of the package's status (bug statistics, porting overview,
-progression in testing, ...).
+progression in <em>testing</em>, ...).
</taglist>
<p>
You can also decide to receive some more information:
to <tt><var>srcpackage</var>_cvs@&pts-host;</tt>. Only people who
accepts the <em>cvs</em> keyword will receive the notifications.
+ <sect id="ddpo">Developer's packages overview
+ <p>
+This is a nice web portal that displays a table of all the packages
+of a single developer (including those where he's listed as
+co-maintainer). The table gives a good summary about his
+packages : number of bugs by severity, list of available versions in each
+distributon, testing status and much more including links to any other
+useful information.
+ <p>
+It is a very good idea to take a look at this table regularly so that
+you don't forget any open bug and so that you don't forget which
+packages are under your responsibility.
+ <p>
+You will find everything here : <url id="&url-ddpo;">
+
<chapt id="pkgs">Managing Packages
<p>
<p>
The <tt>Distribution</tt> field, which originates from the first line of
the <file>debian/changelog</file> file, indicates which distribution the
-package is intended for.
- <p>
-There are three possible values for this field: `stable', `unstable',
-and `experimental'. Normally, packages are uploaded into
-<em>unstable</em>.
+package is intended for.
<p>
-You should avoid combining `stable' with others because of potential
-problems with library dependencies (for your package and for the package
-built by the build daemons for other architecture).
-See <ref id="upload-stable"> for more information on when and how to
-upload to <em>stable</em>.
+There are several possible values for this field: `stable', `unstable',
+`testing-proposed-updates' and `experimental'. Normally, packages are uploaded into
+<em>unstable</em>. Actually, there are two other possible distributions:
+`stable-security' and `testing-security'. However they are used by the
+security team; do not upload there without their agreement.
<p>
-It never makes sense to combine the <em>experimental</em> distribution
-with anything else.
-
-<!--
- <sect2 id="upload-frozen">Uploading to <em>frozen</em>
- <p>
-The Debian freeze is a crucial time for Debian. It is our chance to
-synchronize and stabilize our distribution as a whole. Therefore,
-care must be taken when uploading to <em>frozen</em>.
- <p>
-It is tempting to always try to get the newest release of software
-into the release. However, it's much more important that the system
-as a whole is stable and works as expected.
- <p>
-The watchword for uploading to <em>frozen</em> is <strong>no new
-code</strong>. This is a difficult thing to quantify, so here are
-some guidelines:
- <p>
-<list>
- <item>
-Fixes for bugs of severity <em>critical</em>, <em>grave</em>, or
-<em>serious</em> severity are always allowed for those packages that
-must exist in the final release
- <item>
-<em>critical</em>, <em>grave</em>, and <em>serious</em> bug fixes are
-allowed for non-necessary packages but only if they don't add any new
-features
- <item>
-important, normal and minor bug fixes are allowed (though discouraged)
-on all packages if and only if there are no new features
- <item>
-wishlist fixes are not allowed (they are, after all, not really bugs)
- <item>
-documentation bug fixes are allowed, since good documentation is
-important
- </list>
- <p>
-Experience has shown that there is statistically a 15% chance that
-every bug fix will introduce a new bug. The introduction and
-discovery of new bugs either delays release or weakens the final
-product. There is little correlation between the severity of the
-original bug fixed and the severity of the bug newly introduced by the
-fix.
-
- -->
+It is technically possible to upload a package into several distributions
+at the same time but it usually doesn't make sense to use that feature
+because the dependencies of the package may vary with the distribution.
+In particular, it never makes sense to combine the <em>experimental</em>
+distribution with anything else.
<sect3 id="upload-stable">Uploading to <em>stable</em>
<p>
Uploading to <em>stable</em> means that the package will be placed into the
-<file>proposed-updates</file> directory of the Debian archive for further
+<file>stable-proposed-updates</file> directory of the Debian archive for further
testing before it is actually included in <em>stable</em>.
<p>
Extra care should be taken when uploading to <em>stable</em>. Basically, a
those other packages uninstallable, is strongly discouraged.
<p>
The Release Team (which can be reached at &email-debian-release;) will
-regularly evaluate the uploads in <em>proposed-updates</em> and decide if
+regularly evaluate the uploads in <em>stable-proposed-updates</em> and decide if
your package can be included in <em>stable</em>. Please be clear (and
verbose, if necessary) in your changelog entries for uploads to
<em>stable</em>, because otherwise the package won't be considered for
inclusion.
-
+ <sect3 id="upload-t-p-u">Uploading to <em>testing-proposed-updates</em>
+ <p>
+The testing distribution is fed with packages from unstable according to the rules
+explained in <ref id="testing">. However, the release manager may stop the testing
+scripts when he wants to freeze the distribution. In that case, you may want to
+upload to <em>testing-proposed-udaptes</em> to provide fixed packages during the freeze.
+ <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 manager's eyes, you should read the instructions that he regularly
+gives on &email-debian-devel-announce;.
+ <p>
+You should not upload to <em>testing-proposed-updates</em> when you can update your
+packages through <em>unstable</em>. If you can't (for example because you have a
+newer development version in unstable), you may use it but it is recommended to ask
+the authorization of the release manager before.
<sect1 id="uploading">Uploading a package
slightly different rules than non-porters, due to their unique
circumstances (see <ref id="source-nmu-when-porter">).
<p>
-When a security bug is detected, a fixed package should be uploaded
-as soon as possible. In this case, the Debian security officers get in
-contact with the package maintainer to make sure a fixed package is
-uploaded within a reasonable time (less than 48 hours). If the package
-maintainer cannot provide a fixed package fast enough or if he/she
-cannot be reached in time, a security officer may upload a fixed
-package (i.e., do a source NMU).
+When a security bug is detected, the security team may do an NMU.
+Please refer to <ref id="bug-security"> for more information.
<p>
During the release cycle (see <ref id="sec-dists">), NMUs which fix
serious or higher severity bugs are encouraged and accepted. Even
for the problem. As with any source NMU, the guidelines found in <ref
id="nmu-guidelines"> need to be followed.
<p>
-Bug fixes to unstable by non-maintainers are also acceptable, but only
-as a last resort or with permission. The following protocol should
-be respected to do an NMU:
+Uploading bug fixes to unstable by non-maintainers should only be done
+by following this protocol:
<p>
<list>
<item>
-Make sure that the package's bug is in the Debian Bug Tracking System
-(BTS). If not, submit a bug.
+Make sure that the package's bugs that the NMU is meant to address are all
+filed in the Debian Bug Tracking System (BTS).
+If they are not, submit them immediately.
<item>
Wait a few days the response from the maintainer. If you don't get
any response, you may want to help him by sending the patch that fixes
Follow what happens, you're responsible for any bug that you introduced
with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
to stay informed of the state of the package after your NMU.
- </list>
+</list>
+ <p>
+At times, the release manager or an organized group of developers can
+announce a certain period of time in which the NMU rules are relaxed.
+This usually involves shortening the period during which one is to wait
+before uploading the fixes, and shortening the DELAYED period. It is
+important to notice that even in these so-called "bug squashing party"
+times, the NMUer has to file bugs and contact the developer first,
+and act later.
<sect1 id="nmu-guidelines">How to do a source NMU
<p>
against <tt>ftp.debian.org</tt> asking to remove the package with the
obsolete name. Do not forget to properly reassign the package's bugs
at the same time.
+ <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 <file>foo_1.00.orig.tar.gz</file> with
+<file>foo_1.00+0.orig.tar.gz</file>. This restriction gives each file
+on the ftp site a unique name, which helps to ensure consistency across the
+mirror network.
<sect1 id="orphaning">Orphaning a package
<p>
If this situation is unacceptable, you (or the submitter) may want to
require a decision of the technical committee by reassigning the bug
to <package>tech-ctte</package> (you may use the clone command of
-the BTS if you wish to keep it reported against your package).
-<!-- FIXME: Follow the procedure described at
- tech-ctte-url (there's no such url yet). -->
+the BTS if you wish to keep it reported against your package). Before
+doing so, please read the <url id="&url-tech-ctte;" name="recommended procedure">.
<item>
If the bug is real but it's caused by another package, just reassign
the bug the right package. If you don't know which package it should
read <ref id="upload-bugfix">.
</enumlist>
+ <sect1 id="bug-security">Handling security-related bugs
+ <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 fix them themselves, sending
+security advisories, and maintaining security.debian.org.
+
+<!-- information about the security database goes here once it's ready -->
+<!-- (mdz) -->
+
+ <sect2 id="bug-security-you">What to do when you learn of a
+ security problem
+ <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 at
+&email-security-team;.
+Useful information includes, for example:
+
+<list compact>
+ <item>What versions of the package are known to be affected by the
+ bug.
+
+ <item>The nature of the exposure (root compromise, user compromise,
+ remote/local attack)
+
+ <item>The nature of the fix, if any is available (patches are
+ especially helpful)
+</list>
+
+ <sect2 id="bug-security-confidentiality">Confidentiality
+ <p>
+Unlike most other activities within Debian, information about security
+issues must sometimes be kept private for a time. 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>
+There are a few ways a developer can learn of a security problem:
+
+<list compact>
+ <item>he notices it on a public forum (mailing list, website, etc.)
+ <item>someone files a bug report
+ <item>someone informs him via private email
+</list>
+
+ 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:
+
+<list>
+ <item>if it is a trivial problem (like insecure temporary files)
+ there is no need to keep the problem a secret and a fix should be
+ made and released.
+
+ <item>if the problem is severe (remotely exploitable, possibility to
+ gain root privileges) it is preferable to share the information with
+ other vendors and coordinate a release. The security team keeps
+ contacts with the various organizations and individuals and can take
+ care of that.
+</list>
+
+<p>
+ In all cases if the person who reports the problem asks to not
+ disclose the information that should be respected, with the obvious
+ exception of informing the security team (make sure you tell the
+ security team that the information can not be disclosed).
+
+<p>
+Please note that if secrecy is needed you can also not upload a fix to
+unstable (or anywhere else), since the changelog and diff information
+for unstable is public.
+
+<p>
+There are two reasons for releasing information even though secrecy is
+requested: the problem has been known for too long, or the information
+has become public.
+
+ <sect2 id="bug-security-advisories">Security Advisories
+ <p>
+Security advisories are only issued for the current, released stable
+distribution, not for testing or unstable. When released, advisories
+are sent to the &email-debian-security-announce;
+mailing list and posted on <url
+id="&url-debian-security-advisories;" name="the security web page">.
+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:
+
+<list compact>
+ <item>A description of the problem and its scope, including:
+ <list>
+ <item>The type of problem (privilege escalation, denial of
+ service, etc.)
+ <item>How it can be exploited
+ <item>Whether it is remotely or locally exploitable
+ <item>How the problem was fixed
+ </list>
+ <item>Version numbers of affected packages
+ <item>Version numbers of fixed packages
+ <item>Information on where to obtain the updated packages
+</list>
+
+ <sect2 id="bug-security-building">Preparing packages to
+ address security issues
+ <p>
+One way that you can assist the security team in their duties is to
+provide fixed packages suitable for a security advisory for the stable
+Debian release.
+ <p>
+ When an update is made to the stable release, care must be taken to
+ avoid changing system behaviour 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 behaviour of a release once it is
+ made, so any change we make can possibly 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>
+This means that moving to a new upstream version is not a good
+solution. Instead, the relevant changes should be backported 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>
+In some cases, it is not possible to backport a security fix, for
+example when large amounts of sourcecode need to be modified or
+rewritten. If this happens, it may be necessary to move to a new
+upstream version. However, you must always coordinate that with the
+security team beforehand.
+<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.
+
+When packaging the fix, keep the following points in mind:
+
+<list>
+ <item>Make sure you target the right distribution in your
+ debian/changelog. For stable this is stable-security and for
+ testing this is testing-security. Do not target
+ <em>distribution</em>-proposed-updates!
+
+ <item>Make sure the version number is proper. It must be greater
+ than the current package, but less than package versions in later
+ distributions. If in doubt, test it with <tt>dpkg
+ --compare-versions</tt>. For testing, this means there must be
+ a greater version in unstable. If there is none yet (for example,
+ if testing and unstable have the same version) you must upload a
+ new version to unstable first.
+
+ <item>Do not make source-only uploads if your package has any
+ binary-all packages (do not use the <tt>-S</tt> option to
+ <prgn>dpkg-buildpackage</prgn>). The buildd infrastructure will
+ not build those. This point applies to normal package uploads as
+ well.
+
+ <item>Always build with full source (use the <tt>-sa</tt> option
+ for <prgn>dpkg-buildpackage</prgn>).
+
+ <item>Be sure to use the exact same .orig.tar.gz as used in the
+ normal archive, otherwise it is not possible to move the security
+ fix into the main archives later.
+
+ <item>Be sure, when compiling a package, to compile on a clean
+ system which only has packages installed from the distribution you
+ are building for. If you do not have such a system yourself, you
+ can use a debian.org machine (see <ref id="server-machines">)
+ or setup a chroot (see <ref id="pbuilder"> and
+ <ref id="debootstrap">).
+</list>
+
+ <sect2 id="bug-security-upload">Uploading the fixed package
+<p>
+<em>DO NOT</em> upload a package to the security upload queue 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>
+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
+<tt>ftp://security.debian.org/pub/SecurityUploadQueue/</tt> .
+
+<p>
+Once an upload to the security queue has been accepted, the package
+will automatically be rebuilt for all architectures and stored for
+verification by the security team.
+
+<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>
+If a member of the security team accepts a package, it will be
+installed on security.debian.org as well as the proper
+<em>distribution</em>-proposed-updates on ftp-master or in the non-US
+archive.
<sect1 id="upload-bugfix">When bugs are closed by new uploads
<p>
/etc/modutils/ for module configuration.
-->
+ <sect1 id="bpp-autotools">Packages using autoconf/automake
+ <p>
+Some very good packaging practices for packages using autoconf and/or
+automake have been synthetized in &file-bpp-autotools;. You're strongly
+encouraged to read this file and to follow the given recommandations.
+
+
<sect1 id="bpp-libraries">Libraries
<p>
Libraries are always difficult to package for various reasons. The policy
mistakes. Ensure that you spell check it.
<prgn>ispell</prgn> has a special option (<tt>-g</tt>) for that:
<example>ispell -d american -g debian/control</example>.
-
+If you want someone to proofread the description that you
+intend to use you may ask on &email-debian-l10n-english;.
~ianmdlvl / developers-reference.git / blobdiff