X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=9ae4e099e44cf431b1035b2268f86b0297388c4b;hp=f0c6956bee8964288c17634c8297026877c33033;hb=24cbe1bfd9e63ce3a247fca05f94282f1e69effc;hpb=bb52d6f47f4bf50354bb692fbdb39eebc5756af6 diff --git a/developers-reference.sgml b/developers-reference.sgml index f0c6956..9ae4e09 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
@@ -761,6 +762,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 +1037,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 +1145,7 @@ In general, please refer to the
@@ -1359,9 +1363,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
+When a package is uploaded to the Debian archive, it must be accompanied by
+a .changes control file, which gives directions to the archive
+maintenance software for its handling. This is generated by
+
@@ -1478,25 +1488,27 @@ Remove the package, then reinstall it.
-
-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:
+There are two types of Debian source packages:
+
-&control-file-fields;
+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).
-All of these fields are mandatory for a Debian upload. See the list
-of control fields in the
The first time a version is uploaded which corresponds to a particular
upstream version, the original source tar file should be uploaded and
@@ -1517,17 +1529,20 @@ source tar-file used by
-The Distribution field, which originates 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
@@ -1535,8 +1550,7 @@ 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
The testing distribution is fed with packages from unstable according to the rules
explained in . However, the release manager may stop the testing
@@ -1590,6 +1604,7 @@ 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.
+
-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.
-
@@ -1775,7 +1770,7 @@ 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.
-
The
For more information about override files, see
+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, .
-
-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.
+
+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
+
-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.
+If you want to be a good maintainer, you should periodically check the
+
-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.
+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:
+
-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.
+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.
+
+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.
+
-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.
+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
-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 ).
+ * Frobbed with options (closes: Bug#98339)
+ * Added safety to prevent operator dismemberment, closes: bug#98765,
+ bug#98713, #98714.
+ * Added man page. Closes: #98725.
+
-When a security bug is detected, the security team may do an NMU.
-Please refer to for more information.
+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
-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 .
-
-Uploading bug fixes to unstable by non-maintainers should only be done
-by following this protocol:
-
-
-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.
+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
-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.
+
+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.
+
+
-
-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'.
+
+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:
+
-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.
-
-In addition, the normal maintainer should always retain the
-entry in the changelog file documenting the non-maintainer upload.
+
-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
+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 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 ).
+
-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.
-
-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.
+
+ 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).
-
-See the
+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.
-
-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
+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
-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''.
+
+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
+(
-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.
+When packaging the fix, keep the following points in mind:
-
-
-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.
+
-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
+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:
-
+See the
-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.
+The way to invoke
-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.
-
-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.
-
-
-
-
-
-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:
+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''.
-
-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:
-
-
+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 .
- 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).
+
+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
-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.
+
+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.
-
-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
+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.
+
+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.
-
-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
-(
+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.
-When packaging the fix, keep the following points in mind:
+
+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 ).
+
+When a security bug is detected, the security team may do an NMU.
+Please refer to for more information.
+
+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 .
+
+Uploading bug fixes to unstable by non-maintainers should only be done
+by following this protocol:
+
+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.
-
+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'.
-
+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
+
-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.
+
+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.
+
+In addition, the normal maintainer should always retain the
+entry in the changelog file documenting the non-maintainer upload.
-
-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.
+
+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 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.
+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.
-However, it's possible to avoid having to manually close bugs after the
-upload -- just list the fixed bugs in your
+
-
-
+
-
+
+ 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:
-
+
-
+
+
+
+
-
-
-
-
-
- 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:
+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.
-
+
-
-
-
-
-
+