X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=dcaced2e7dd34165a0c6d573556d80b8ad9112ca;hb=4429914d13bcd922d5f29aae420b19697f7ffe1b;hp=f0c6956bee8964288c17634c8297026877c33033;hpb=bb52d6f47f4bf50354bb692fbdb39eebc5756af6;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index f0c6956..dcaced2 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - +
The procedures discussed within include how to become a maintainer
-(); how to upload new packages (); how and when to do ports and interim releases of other
-maintainers' packages (); how to move, remove, or orphan
-packages (); and how to handle bug reports
-().
+(); how to create new packages
+() and how to upload packages ();
+how to handle bug reports (); how to move,
+remove, or orphan packages (); how to port
+packages (); and how and when to do interim
+releases of other maintainers' packages ().
The resources discussed in this reference include the mailing lists
() and servers (); a
@@ -277,6 +278,7 @@ at
You have to keep the information available there up-to-date.
+
Be very careful with your private keys. Do not place them on any
@@ -297,43 +299,54 @@ the documentation of the
-Even if Debian is not always a real democracy, Debian has democratic
-tools and uses a democratic process to elect its leader or
-to approve a general resolution. Those processes are described in
-the
+Other than the yearly leader election, votes are not routinely held, and
+they are not undertaken lightly. Each proposal is first discussed on
+the &email-debian-vote; mailing list and it requires several endorsements
+before the project secretary starts the voting procedure.
-Democratic processes work well only if everybody take part in the
-vote, that's why you have to vote. To be able to vote you have to
-subscribe to &email-debian-devel-announce; since call for votes are sent
-there. If you want to follow the debate preceding a vote, you
-may want to subscribe to &email-debian-vote;.
+You don't have to track the pre-vote discussions, as the secretary will
+issue several calls for votes on &email-debian-devel-announce; (and all
+developers are expected to be subscribed to that list). Democracy doesn't
+work well if people don't take part in the vote, which is why we encourage
+all developers to vote. Voting is conducted via GPG-signed/encrypted emails
+messages.
The list of all the proposals (past and current) is available on the
-
-Most developers take vacations, and usually this means that they can't
-work for Debian and they can't be reached by email if any problem occurs.
-The other developers need to know that you're on vacation so that they'll
-do whatever is needed when such a problem occurs. Usually this means that
-other developers are allowed to NMU (see ) your package if a
-big problem (release critical bugs, security update, etc.) occurs while
-you're on vacation.
+It is common for developers to have periods of absence, whether those are
+planned vacations or simply being buried in other work. The important thing
+to notice is that the other developers need to know that you're on vacation
+so that they can do whatever is needed if a problem occurs with your
+packages or other duties in the project.
+
+Usually this means that other developers are allowed to NMU (see
+) your package if a big problem (release critical bugs,
+security update, etc.) occurs while you're on vacation. Sometimes it's
+nothing as critical as that, but it's still appropriate to let the others
+know that you're unavailable.
In order to inform the other developers, there's two things that you should do.
-First send a mail to &email-debian-private; giving the period of time when
-you will be on vacation. You can also give some special instructions on what to
-do if any problem occurs. Be aware that some people don't care for vacation
-notices and don't want to read them; you should prepend "[VAC] " to the
-subject of your message so that it can be easily filtered.
+First send a mail to &email-debian-private; with "[VAC] " prepended to the
+subject of your message
-Next you should update your information
-available in the Debian LDAP database and mark yourself as ``on vacation''
-(this information is only accessible to debian developers). Don't forget
-to remove the ``on vacation'' flag when you come back!
+The other thing to do is to mark yourself as "on vacation" in the
+
@@ -354,6 +367,7 @@ developers which can be included there, so that you won't have to
modify the sources of the next upstream version. Whatever changes you
need, always try not to fork from the upstream sources.
+
Generally you should deal with bug reports on your packages as described in
@@ -513,7 +527,7 @@ all the files.
There are other additional channels dedicated to specific subjects.
#debian-bugs is used for coordinating bug squash parties.
#debian-boot is used to coordinate the work on the boot
-floppies (i.e. the installer). #debian-doc is
+floppies (i.e., the installer). #debian-doc is
occasionally used to talk about documentation, like the document you are
reading. Other channels are dedicated to an architecture or a set of
packages: #debian-bsd, #debian-kde, #debian-jr,
@@ -761,6 +775,13 @@ On the other hand, a CD-ROM vendor could easily check the individual
package licenses of the packages in non-free and include as
many on the CD-ROMs as he's allowed to. (Since this varies greatly from
vendor to vendor, this job can't be done by the Debian developers.)
+
+Note also that the term "section" is also used to refer to categories
+which simplify the organization and browsing of available packages, e.g.
+admin, net, utils etc. Once upon a time, these
+sections (subsections, rather) existed in the form of subdirectories within
+the Debian archive. Nowadays, these exist only in the "Section" header
+fields of packages.
@@ -1043,7 +1050,15 @@ the other packages. Once all the other updates (generating new
made, a special script is called to ask all the primary mirrors to update
themselves.
-All debian developers have write access to the
+All Debian developers have write access to the
+
The
@@ -1142,6 +1158,7 @@ In general, please refer to the
@@ -1359,9 +1376,8 @@ packages are under your responsibility.
This chapter contains information related to creating, uploading,
maintaining, and porting packages.
-
If you want to create a new package for the Debian distribution, you
should first check the
Changes that you make to the package need to be recorded in the
The
@@ -1444,11 +1460,12 @@ contains a new upstream version of the software looks like this:
There are tools to help you create entries and finalize the
+See also .
-
-
+
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):
@@ -1471,6 +1488,9 @@ to emit errors (they will start with E).
For more information on
-When a package is uploaded to the Debian FTP archive, it must be
-accompanied by a
-The changes file is a control file with the following fields:
-
-&control-file-fields;
-
-All of these fields are mandatory for a Debian upload. See the list
-of control fields in the
+
+There are two types of Debian source packages:
+
+For the native packages, the source package includes a Debian source control
+file (.dsc) and the source tarball (.tar.gz). A source
+package of a non-native package includes a Debian source control file, the
+original source tarball (.orig.tar.gz) and the Debian patches
+(.diff.gz).
+
+Whether a package is native or not is determined when it is built by
+
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
+
By default,
+
If no original source is included in the upload, the original
source tar-file used by
-The Distribution field, which originates from the first line of
-the
+
+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
There are several possible values for this field: `stable', `unstable',
-`testing-proposed-updates' and `experimental'. Normally, packages are uploaded into
-unstable. 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.
-
+`testing-proposed-updates' and `experimental'. Normally, packages are
+uploaded into unstable.
+
+Actually, there are two other possible distributions: `stable-security' and
+`testing-security', but read for more information on
+those.
+
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 experimental
distribution with anything else.
-
-
+
Uploading to stable means that the package will be placed into the
+
Extra care should be taken when uploading to stable. Basically, a
package should only be uploaded to stable if one of the following happens:
+
It is discouraged to change anything else in the package that isn't
important, because even trivial fixes can cause bugs later on. Uploading
new upstream versions to fix security problems is deprecated; applying the
specific patch from the new upstream version to the old one ("back-porting"
the patch) is the right thing to do in most cases.
-
+
Packages uploaded to stable need to be compiled on systems running
stable, so that their dependencies are limited to the libraries
(and other packages) available in stable; for example, a package
@@ -1564,7 +1588,7 @@ uploaded to stable that depends on a library package that only
exists in unstable will be rejected. Making changes to dependencies of other
packages (by messing with Provides or shlibs files), possibly making
those other packages uninstallable, is strongly discouraged.
-
+
The Release Team (which can be reached at &email-debian-release;) will
regularly evaluate the uploads in stable-proposed-updates and decide if
your package can be included in stable. Please be clear (and
@@ -1572,34 +1596,37 @@ verbose, if necessary) in your changelog entries for uploads to
stable, because otherwise the package won't be considered for
inclusion.
-
+
The testing distribution is fed with packages from unstable according to the rules
explained in . 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 testing-proposed-updates to provide fixed packages during the freeze.
-
+
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;.
-
+
You should not upload to testing-proposed-updates when you can update your
packages through unstable. 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.
-
To upload a package, you need a personal account on
+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. If you don't want to bother with transferring
@@ -1627,10 +1654,12 @@ process of uploading packages into Debian.
After uploading your package, you can check how the archive
maintenance software will process it by running
Note that
As discussed above, export controlled software should not be uploaded
to ftp-master. Instead, upload the package to
@@ -1674,7 +1703,7 @@ advice. Again, it is strongly recommended that U.S. citizens and
residents consult a lawyer before doing uploads to non-US.
-
If you have a slow network connection to ftp-master, there are
alternatives. One is to upload files to
Another upload queue is available in Germany: just upload the files
via anonymous FTP to
Another upload queue is available which is based in the US, and is a
good backup when there are problems reaching ftp-master. You can
@@ -1733,26 +1762,6 @@ An upload queue is available in Japan: just upload the files via
anonymous FTP to
-When a package is uploaded, an announcement should be posted to one of
-the ``debian-changes'' lists. This is now done automatically by the archive
-maintenance software when it runs (usually once a day). You just need to use
-a recent
-If a package is released with the Distribution: set to
-`stable', the announcement is sent to &email-debian-changes;. If a
-package is released with Distribution: set to `unstable',
-or `experimental', the announcement will be
-posted to &email-debian-devel-changes; instead.
-
@@ -1774,16 +1783,19 @@ checking if any bugs you meant to close didn't get triggered.
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.
+
+Note also that if you upload via queues, the queue daemon software will
+also send you a notification by email.
-
+
The
+
The archive maintainers keep track of the canonical sections and
priorities for packages in the override file. If there is a
disparity between the override file and the package's fields
@@ -1792,567 +1804,441 @@ email noting the divergence when the package is installed into the
archive. You can either correct your
+
To alter the actual section that a package is put in, you need to
first make sure that the
-For more information about override files, see
-Under certain circumstances it is necessary for someone other than the
-official package maintainer to make a release of a package. This is
-called a non-maintainer upload, or NMU.
-
-Debian porters, who compile packages for different architectures,
-occasionally do binary-only NMUs as part of their porting activity
-(see ). Another reason why NMUs are done is when a
-Debian developers needs to fix another developers' packages in order to
-address serious security problems or crippling bugs, especially during
-the freeze, or when the package maintainer is unable to release a fix
-in a timely fashion.
-
-This chapter contains information providing guidelines for when and
-how NMUs should be done. A fundamental distinction is made between
-source and binary-only NMUs, which is explained in the next section.
-
-
-There are two new terms used throughout this section: ``binary-only NMU''
-and ``source NMU''. These terms are used with specific technical
-meaning throughout this document. Both binary-only and source NMUs are
-similar, since they involve an upload of a package by a developer who
-is not the official maintainer of that package. That is why it's a
-non-maintainer upload.
-
-A source NMU is an upload of a package by a developer who is not the
-official maintainer, for the purposes of fixing a bug in the package.
-Source NMUs always involves changes to the source (even if it is just
-a change to
-A binary-only NMU is a recompilation and upload of a binary package
-for a given architecture. As such, it is usually part of a porting
-effort. A binary-only NMU is a non-maintainer uploaded binary version
-of a package, with no source changes required. There are many cases
-where porters must fix problems in the source in order to get them to
-compile for their target architecture; that would be considered a
-source NMU rather than a binary-only NMU. As you can see, we don't
-distinguish in terminology between porter NMUs and non-porter NMUs.
+For more information about override files, see
-Both classes of NMUs, source and binary-only, can be lumped by the
-term ``NMU''. However, this often leads to confusion, since most
-people think ``source NMU'' when they think ``NMU''. So it's best to
-be careful. In this chapter, if we use the unqualified term ``NMU'',
-we refer to any type of non-maintainer upload NMUs, whether source and
-binary, or binary-only.
+Note also that the term "section" is used for the separation of packages
+according to their licensing, e.g. main, contrib and
+non-free. This is described in another section, .
-
-Only official, registered Debian maintainers can do binary or source
-NMUs. An official maintainer is someone who has their key in the
-Debian key ring. Non-developers, however, are encouraged to download
-the source package and start hacking on it to fix problems; however,
-rather than doing an NMU, they should just submit worthwhile patches
-to the Bug Tracking System. Maintainers almost always appreciate
-quality patches and bug reports.
-
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned. The
+
-Guidelines for when to do a source NMU depend on the target
-distribution, i.e., stable, unstable, or experimental. Porters have
-slightly different rules than non-porters, due to their unique
-circumstances (see ).
+If you want to be a good maintainer, you should periodically check the
+
-When a security bug is detected, the security team may do an NMU.
-Please refer to for more information.
+Maintainers interact with the BTS via email addresses at
+&bugs-host;. Documentation on available commands can be
+found at
-During the release cycle (see ), NMUs which fix
-serious or higher severity bugs are encouraged and accepted. Even
-during this window, however, you should endeavor to reach the current
-maintainer of the package; they might be just about to upload a fix
-for the problem. As with any source NMU, the guidelines found in need to be followed. Special exceptions are made
-for .
+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:
+
-Uploading bug fixes to unstable by non-maintainers should only be done
-by following this protocol:
+Make sure that any discussion you have about bugs are sent both to
+the original submitter of the bug, and the bug itself (e.g.,
+
-
-At times, the release manager or an organized group of developers can
-announce a certain period of time in which the NMU rules are relaxed.
-This usually involves shortening the period during which one is to wait
-before uploading the fixes, and shortening the DELAYED period. It is
-important to notice that even in these so-called "bug squashing party"
-times, the NMU'er has to file bugs and contact the developer first,
-and act later.
+You should never close bugs via the bug server close
+command sent to &email-bts-control;. If you do so, the original
+submitter will not receive any information about why the bug was
+closed.
-
-The following applies to porters insofar as they are playing the dual
-role of being both package bug-fixers and package porters. If a
-porter has to change the Debian source archive, automatically their
-upload is a source NMU and is subject to its rules. If a porter is
-simply uploading a recompiled binary package, the rules are different;
-see .
+
-First and foremost, it is critical that NMU patches to source should
-be as non-disruptive as possible. Do not do housekeeping tasks, do
-not change the name of modules or files, do not move directories; in
-general, do not fix things which are not broken. Keep the patch as
-small as possible. If things bother you aesthetically, talk to the
-Debian maintainer, talk to the upstream maintainer, or submit a bug.
-However, aesthetic changes must not be made in a non-maintainer
-upload.
-
-
-
-Whenever you have made a change to a package, no matter how trivial,
-the version number needs to change. This enables our packing system
-to function.
-
-If you are doing a non-maintainer upload (NMU), you should add a new
-minor version number to the debian-revision part of the
-version number (the portion after the last hyphen). This extra minor
-number will start at `1'. For example, consider the package `foo',
-which is at version 1.1-3. In the archive, the source package control
-file would be
-The Debian revision minor number is needed to avoid stealing one of
-the package maintainer's version numbers, which might disrupt their
-work. It also has the benefit of making it visually clear that a
-package in the archive was not made by the official maintainer.
-
-If there is no debian-revision component in the version
-number then one should be created, starting at `0.1'. If it is
-absolutely necessary for someone other than the usual maintainer to
-make a release based on a new upstream version then the person making
-the release should start with the debian-revision value
-`0.1'. The usual maintainer of a package should start their
-debian-revision numbering at `1'.
+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 interesting to developers
+are described in the
+Filing bugs for problems that you find in other packages is one of
+the "civic obligations" of maintainership, see
+for details. However, handling the bugs in your own packages is
+even more important.
+
+Here's a list of steps that you may follow to handle a bug report:
+
+If the bug submitter disagree 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 wontfix
+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
+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.
+
+If you fix a bug in your packages, it is your responsibility as the
+package maintainer to close the bug when it has been fixed. However,
+you should not close the 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.
+
+However, it's possible to avoid having to manually close bugs after the
+upload -- just list the fixed bugs in your
-A non-maintainer doing a source NMU must create a changelog entry,
-describing which bugs are fixed by the NMU, and generally why the NMU
-was required and what it fixed. The changelog entry will have the
-non-maintainer's email address in the log entry and the NMU version
-number in it.
-
-By convention, source NMU changelog entries start with the line
-Maintainers other than the official package maintainer should make as
-few changes to the package as possible, and they should always send a
-patch as a unified context diff (diff -u) detailing their
-changes to the Bug Tracking System.
-
-What if you are simply recompiling the package? If you just need to
-recompile it for a single architecture, then you may do a binary-only
-NMU as described in which doesn't require any
-patch to be sent. If you want the package to be recompiled for all
-architectures, then you do a source NMU as usual and you will have to
-send a patch.
-
-If the source NMU (non-maintainer upload) fixes some existing bugs,
-these bugs should be tagged fixed in the Bug Tracking
-System rather than closed. By convention, only the official package
-maintainer or the original bug submitter are allowed to close bugs.
-Fortunately, Debian's archive system recognizes NMUs and thus marks
-the bugs fixed in the NMU appropriately if the person doing the NMU
-has listed all bugs in the changelog with the Closes:
-bug#nnnnn syntax (see for
-more information describing how to close bugs via the changelog).
-Tagging the bugs fixed ensures that everyone knows that the
-bug was fixed in an NMU; however the bug is left open until the
-changes in the NMU are incorporated officially into the package by
-the official package maintainer.
-
-Also, after doing an NMU, you have to open a new bug and include a
-patch showing all the changes you have made. Alternatively you can send
-that information to the existing bugs that are fixed by your NMU.
-The normal maintainer will either apply the patch or employ an alternate
-method of fixing the problem. Sometimes bugs are fixed independently
-upstream, which is another good reason to back out an NMU's patch.
-If the maintainer decides not to apply the NMU's patch but to release a
-new version, the maintainer needs to ensure that the new upstream version
-really fixes each problem that was fixed in the non-maintainer release.
+The author prefers the closes: #XXX syntax, as
+one of the most concise and easiest to integrate with the text of the
+
+If you happen to mistype a bug number or forget one in the changelog file,
+don't hesitate to undo any damage the error caused. To reopen wrongly closed
+bugs, send an reopen XXX command in the bug tracking
+system's control bot. To close any remaining bugs that were fixed by your
+upload, email the
+Bear in mind that it is not obligatory to close bugs using the changelog
+like described above -- if you simply want to close bugs that don't have
+anything to do with an upload of yours, do it simply by emailing an
+explanation to
-In addition, the normal maintainer should always retain the
-entry in the changelog file documenting the non-maintainer upload.
+For general information on what to put in the changelog files, please
+refer to .
+
+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.
-
-Source NMU packages are built normally. Pick a distribution using the
-same rules as found in . Just as described in
-, a normal changes file, etc., will be built. In
-fact, all the prescriptions from apply.
-
-Make sure you do not change the value of the maintainer in
-the
-If one of your packages has been NMU'ed, you have to incorporate the
-changes in your copy of the sources. This is easy, you just have
-to apply the patch that has been sent to you. Once this is done, you
-have to close the bugs that have been tagged fixed by the NMU. You
-can either close them manually by sending the required mails to the
-BTS or by adding the required closes: #nnnn in the changelog
-entry of your next upload.
-
-In any case, you should not be upset by the NMU. An NMU is not a
-personal attack against the maintainer. It is a proof that
-someone cares enough about the package and that they were willing to help
-you in your work, so you should be thankful. You may also want to
-ask them if they would be interested to help you on a more frequent
-basis as co-maintainer or backup maintainer
-(see ).
+
+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:
+
-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.
-
-Porting is the act of building Debian packages for architectures that
-is different from the original architecture of the package
-maintainer's binary package. It is a unique and essential activity.
-In fact, porters do most of the actual compiling of Debian packages.
-For instance, for a single i386 binary package, there must be
-a recompile for each architecture, which amounts to
-&number-of-arches; more builds.
+
-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.
-
-The first and most important watchword 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,
-doing your best to hunt down whatever the problem is.
-
+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.
+
+There are a few ways a developer can learn of a security problem:
-
-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 instead.
-
-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
-The way to invoke
-Sometimes the initial porter upload is problematic because the environment
-in which the package was built was not good enough (outdated or obsolete
-library, bad compiler, ...). Then you may just need to recompile it in
-an updated environment. However, you have to bump the version number in
-this case, so that the old bad package can be replaced in the Debian archive
-(
-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).
-
-The ``magic'' for a recompilation-only NMU is triggered by using the
-third-level number on the Debian part of the version. For instance,
-if the latest version you are recompiling against was version
-``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the
-latest version was ``3.4-2.1'', your NMU should have a version number
-of ``3.4-2.1.1''.
+ 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:
+
-Porters doing a source NMU generally follow the guidelines found in
-, 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.
+
-However, if you are a porter doing an NMU for `unstable', the above
-guidelines for porting should be followed, with two variations.
-Firstly, the acceptable waiting period — the time between when the
-bug is submitted to the BTS and when it is OK to do an NMU — is seven
-days for porters working on the unstable distribution. This period
-can be shortened if the problem is critical and imposes hardship on
-the porting effort, at the discretion of the porter group. (Remember,
-none of this is Policy, just mutually agreed upon guidelines.)
-
-Secondly, porters doing source NMUs should make sure that the bug they
-submit to the BTS should be of severity `serious' or greater. This
-ensures that a single source package can be used to compile every
-supported Debian architecture by release time. It is very important
-that we have one version of the binary and source package for all
-architecture in order to comply with many licenses.
-
-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
-compilers bugs and the like, make sure you #ifdef your work
-properly; also, document your kludge so that people know to remove it
-once the external problems have been fixed.
-
-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.
+
+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.
+
+There are two reasons for releasing information even though secrecy is
+requested: the problem has been known for a while, or that the problem
+or exploit has become public.
-
-There is infrastructure and several tools to help automate the 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.
-Web pages containing the status of each port can be found at
-Each port of Debian has a mailing list. The list of porting mailing
-lists can be found at
-Descriptions of several porting tools can be found in .
-The
-
-Some of the data produced by
-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
+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.
+
+ 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.
+
+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.
+
+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, you must always coordinate that with the
+security team beforehand.
+
+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.
+
+Review and test your changes as much as possible. Check the
+differences from the previous version repeatedly
+(
+When packaging the fix, keep the following points in mind:
+
+DO NOT 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.
+
+DO NOT upload your fix to proposed-updates without
+coordinating with the security team. Packages from
+security.debian.org will be copied into the proposed-updates directory
+automatically. If a package with the same or a higher version number
+is already installed into the archive, the security update will be
+rejected by the archive system. That way, the stable distribution
+will end up without a security update for this package instead.
+
+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
+ftp://security.debian.org/pub/SecurityUploadQueue/ .
+
+
+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.
+
+
+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.
+
+
+If a member of the security team accepts a package, it will be
+installed on security.debian.org as well as the proper
+distribution-proposed-updates on ftp-master or in the non-US
+archive.
-
-"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 time. It is strongly recommended that
-packages in which a priority of Standard or which are part of
-the base set have co-maintainers.
-Generally there is a primary maintainer and one or more
-co-maintainers. The primary maintainer is the whose name is listed in
-the Maintainer field of the
-In its most basic form, the process of adding a new co-maintainer is
-quite easy:
-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
-Add the co-maintainer's correct maintainer name and address to the
-Uploaders field in the global part of the
-
-Using the PTS (), the co-maintainers
-should subscribe themselves to the appropriate source package.
-Often as a package maintainer, you find bugs in other packages or else
-have bugs reported to your packages which need to be reassigned. The
-
+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.
+
+Porting is the act of building Debian packages for architectures that
+is different from the original architecture of the package
+maintainer's binary package. It is a unique and essential activity.
+In fact, porters do most of the actual compiling of Debian packages.
+For instance, for a single i386 binary package, there must be
+a recompile for each architecture, which amounts to
+&number-of-arches; more builds.
-
-If you want to be a good maintainer, you should periodically check the
-
-Maintainers interact with the BTS via email addresses at
-&bugs-host;. Documentation on available commands can be
-found at
-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:
-
-Make sure that any discussion you have about bugs are sent both to
-the original submitter of the bug, and the bug itself (e.g.,
-
-Once you've dealt with a bug report (e.g. fixed it), mark it as
-done (close it) by sending an explanation message to
-
-You should never close bugs via the bug server close
-command sent to &email-bts-control;. If you do so, the original
-submitter will not receive any information about why the bug was
-closed.
+By far, most of the problems encountered by porters are caused by
+packaging bugs in the source packages. Here is a checklist
+of things you should check or be aware of.
-
-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 interesting to developers
-are described in the
-Filing bugs for problems that you find in other packages is one of
-the "civic obligations" of maintainership, see
-for details. However, handling the bugs in your own packages is
-even more important.
-
-Here's a list of steps that you may follow to handle a bug report:
-If the bug submitter disagree 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 wontfix
-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
-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.
-
+If you can't set up a proper chroot,
+See the
-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.
-
-
+
+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 instead.
+
+
+
@@ -1550,13 +1574,13 @@ package should only be uploaded to stable if one of the following happens:
-
-
+Once you've dealt with a bug report (e.g. fixed it), mark it as
+done (close it) by sending an explanation message to
+
+
+
+
-
+
-
-
+
-
+
+
+
+
+
-