X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=d9b32af5d320e7f2ac8c2b74e5b12760c5aca8e2;hp=89ba78fc4c9ba549ac895c674fd54deb284c4f5d;hb=29d894ef84ae1a1583cfa162475c7c5a36bea9c9;hpb=4961519caa41c56bfa83372062f43aac5bfb4aec;ds=sidebyside diff --git a/developers-reference.sgml b/developers-reference.sgml index 89ba78f..d9b32af 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -2,16 +2,15 @@ %versiondata; - + %commondata; - + + - + revision of the original developer's reference in cvs-en-rev --> + FIXME: "> @@ -22,7 +21,8 @@
It should be clear that this reference does not discuss the technical
-details of the Debian package nor how to generate Debian packages.
+details of Debian packages nor how to generate them.
Nor does this reference detail the standards to which Debian software
must comply. All of such information can be found in the
Furthermore, this document is not an expression of formal
policy. It contains documentation for the Debian system and
-generally agreed-upon best practices. Thus, it is what is called a
+generally agreed-upon best practices. Thus, it is not what is called a
``normative'' document.
@@ -114,19 +116,20 @@ to work on something to avoid duplicated effort.
Another good list to subscribe to is &email-debian-mentors;. See for details. The IRC channel #debian can also be
-helpful.
+helpful; see .
When you know how you want to contribute to &debian-formal;, you
should get in contact with existing Debian maintainers who are working
on similar tasks. That way, you can learn from experienced developers.
For example, if you are interested in packaging existing software for
-Debian you should try to get a sponsor. A sponsor will work together
+Debian, you should try to get a sponsor. A sponsor will work together
with you on your package and upload it to the Debian archive once they
are happy with the packaging work you have done. You can find a sponsor
by mailing the &email-debian-mentors; mailing list, describing your
package and yourself and asking for a sponsor (see
-for more information on sponsoring). On the other hand, if you are
+and
@@ -172,7 +175,7 @@ has been signed by an existing Debian maintainer. If your GnuPG key
is not signed yet, you should try to meet a Debian maintainer in
person to get your key signed. There's a
+
The recommended public key algorithm for use in Debian development
-work is DSA (sometimes call ``DSS'' or ``DH/ElGamal''). Other key
-types may be used however. Your key length must be at least 1024
+work is DSA (sometimes called ``DSS'' or ``DH/ElGamal'').
+Other key types may be used, however. Your key length must be at least 1024
bits; there is no reason to use a smaller key, and doing so would be
much less secure. Your key must be signed with at least your own user
ID; this prevents user ID tampering.
If you wish to be a mentor and/or sponsor, more information is
available in .
@@ -285,11 +294,26 @@ public servers or multiuser machines, such as the Debian servers
Read the documentation that comes with your software; read the
+You need to ensure not only that your key is secure against being stolen,
+but also that it is secure against being lost. Generate and make a copy
+(best also in paper form) of your revocation certificate; this is needed if
+your key is lost.
+
If you add signatures to your public key, or add user identities, you
can update the Debian key ring by sending your key to the key server at
-&keyserver-host;. If you need to add a completely new key,
-or remove an old key, send mail to &email-debian-keyring;. The same
-key extraction routines discussed in apply.
+&keyserver-host;.
+
+If you need to add a completely new key or remove an old key, you need
+to get the new key signed by another developer. After this, a mail
+signed by another developer listing your account name, the keyids
+of the old and of the new key and the reason should be send to
+&email-debian-keyring;. If the old key is compromised or invalid, you
+also have to add the revocation certificate. If there is no real
+reason for a new key, the Keyring Maintainers will only accept it if
+it's more secure and connected to the old key.
+
+The same key extraction routines discussed in
+apply.
You can find a more in-depth discussion of Debian key maintenance in
the documentation of the
-In order to inform the other developers, there's two things that you should do.
+In order to inform the other developers, there are two things that you should do.
First send a mail to &email-debian-private; with "[VAC] " prepended to the
subject of your message
+Ideally, you should sign up at the
+
If you need to modify the upstream sources in order to build a policy
@@ -371,7 +402,7 @@ need, always try not to fork from the upstream sources.
Generally you should deal with bug reports on your packages as described in
. However, there's a special category of bugs that
-you need to take care of -- the so-called release-critical bugs (RC bugs).
+you need to take care of — the so-called release-critical bugs (RC bugs).
All bug reports that have severity critical, grave or
serious are considered to have an impact on whether the package can
be released in the next stable release of Debian.
@@ -515,7 +546,7 @@ on Debian, it's not a support channel (there's #debian for that).
It is however open to anyone who wants to lurk (and learn). Its topic is
commonly full of interesting information for developers.
-Since #debian-devel it's an open channel, you
+Since #debian-devel is an open channel, you
should not speak there of issues that are discussed in
&email-debian-private;. There's another channel for this purpose,
it's called #debian-private and it's protected by a key.
@@ -526,8 +557,8 @@ 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
+#debian-boot is used to coordinate the work on the debian-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,
@@ -542,12 +573,23 @@ French speaking people interested in Debian's development.
Channels dedicated to Debian also exist on other IRC networks, notably on
the
+To get a cloak on freenode, you send Göran Weinholt <weinholt@debian.org>
+a signed mail where you tell what your nick is.
+Put "cloak" somewhere in the Subject: header.
+The nick should be registered:
+
-This document contains a lot of information very useful to Debian developers,
-but it can not contain everything. Most of the other interesting documents
+This document contains a lot of information
+which is useful to Debian developers,
+but it cannot contain everything. Most of the other interesting documents
are linked from
+Some of the core servers are restricted, but the information from there
+is mirrored to another server.
&bugs-host; is the canonical location for the Bug Tracking
-System (BTS). If you plan on doing some statistical analysis or
+System (BTS).
+
+It is restricted; a mirror is available on merkel.
+
+If you plan on doing some statistical analysis or
processing of Debian bugs, this would be the place to do it. Please
describe your plans on &email-debian-devel; before implementing
anything, however, to reduce unnecessary duplication of effort or
wasted processing time.
-
-All Debian developers have accounts on &bugs-host;.
@@ -608,6 +655,8 @@ The ftp-master.debian.org server holds the canonical copy of the Debian
archive (excluding the non-US packages). Generally, package uploads
go to this server; see .
+It is restricted; a mirror is available on merkel.
+
Problems with the Debian FTP archive generally need to be reported as
bugs against the
Our CVS server is located on cvs.debian.org.
@@ -678,6 +728,20 @@ To request a CVS area, send a request via email to
&email-debian-admin;. Include the name of the requested CVS area,
the Debian account that should own the CVS root area, and why you need it.
+
+On some machines, there are chroots to different distributions available.
+You can use them like
+
+
@@ -706,7 +770,7 @@ Most of the information is not accessible to the public, naturally.
For more information please read the online documentation that you can find
at
-One can also submit their SSH keys to be used for authorization on the
+Developers can also submit their SSH keys to be used for authorization on the
official Debian machines, and even add new *.debian.net DNS entries.
Those features are documented at
The main section of the Debian archive is what makes up the
official &debian-formal; distribution. The
@@ -785,10 +849,10 @@ commercial distribution, for example.
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
+many on the CD-ROMs as it'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
+Note 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
@@ -818,7 +882,7 @@ also have ports underway to non-Linux kernels. Aside from
shipped for i386 and m68k architectures. Debian 2.1
ships for the i386, m68k, alpha, and
sparc architectures. Debian 2.2 added support for the
-powerpc and arm architectures. Debian 3.0 adds
+powerpc and arm architectures. Debian 3.0 added
support of five new architectures: ia64, hppa,
s390, mips and mipsel.
@@ -864,7 +928,7 @@ server. For instance, at the mirror site,
contained in
-A distribution is comprised of Debian source and binary packages, and the
+A distribution comprises Debian source and binary packages, and the
respective
There are always distributions called stable (residing in
-
@@ -883,11 +947,12 @@ Active development is done in the unstable distribution
(that's why this distribution is sometimes called the development
distribution). Every Debian developer can update his or her
packages in this distribution at any time. Thus, the contents of this
-distribution changes from day-to-day. Since no special effort is done
+distribution change from day to day. Since no special effort is made
to make sure everything in this distribution is working properly, it is
sometimes literally unstable.
-
+Packages are usually installed into the `testing' distribution after they
+have undergone some degree of testing in unstable.
-The scripts that update the testing distribution are run each
-day after the installation of the updated packages. They generate the
-
-The inclusion of a package from unstable is conditional on
-the following:
-
-To find out whether a package is progressing into testing or not, see the
-testing script output on the
-The
-Sometimes, some packages never enter testing because the set of
-inter-relationship is too complicated and cannot be sorted out
-by the scripts. In that case, the release manager must be
-contacted, and he will force the inclusion of the packages.
-
-In general, please refer to the
@@ -1030,7 +1048,10 @@ New software which isn't likely to damage your system can go directly into
An alternative to experimental is to use your personal web space
on people.debian.org.
-
+
+When uploading to unstable a package which had bugs fixed in experimental,
+please consider using the option -v to
@@ -1103,23 +1124,34 @@ directories and scripts that are installed both on &ftp-master-host;
and &non-us-host;.
Packages are uploaded by all the maintainers into a directory called
-
-Once the package is accepted the system sends a confirmation
-mail to the maintainer, closes all the bugs marked as fixed by the upload
+the package (or it has new binary packages),
+it is moved to the
+Once the package is accepted, the system sends a confirmation
+mail to the maintainer and closes all the bugs marked as fixed by the upload,
and the auto-builders may start recompiling it. The package is now publicly
-accessible at
+Though ftp-master is restricted, a copy of the installation is available
+to all developers on &ftp-master-mirror;.
+
The bug tracking system tracks bugs for each package.
You can view the bugs of a given package at the URL
@@ -1200,7 +1240,8 @@ You can view the bugs of a given package at the URL
In this example, you can see that the version in unstable differs from
the version in testing and that there has been a binary-only NMU of the
-package for the alpha architecture. Each time the package has been
+package for the alpha architecture. Each version of the package has been
recompiled on most of the architectures.
If you use a publicly accessible CVS repository for maintaining
-your Debian package you may want to forward the commit notification
+your Debian package, you may want to forward the commit notification
to the PTS so that the subscribers (and possible co-maintainers) can
closely follow the package's evolution.
@@ -1514,7 +1555,7 @@ you must then submit a bug report () against the
pseudo-package
You should set the subject of the bug to ``ITP: foo
@@ -1525,10 +1566,10 @@ to wishlist. If you feel it's necessary, send a copy to
of the message (no, don't use CC:, because that way the message's subject
won't indicate the bug number).
-Please include a Closes: bug#nnnnn entry on the
+Please include a Closes: bug#nnnnn entry in the
changelog of the new package in order for the bug report to be
-automatically closed once the new package is installed on the archive
-().
+automatically closed once the new package is installed in the archive
+(see ).
There are a number of reasons why we ask maintainers to announce their
intentions:
@@ -1677,11 +1718,8 @@ 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 (see ).
+It is not possible to upload a package into several distributions
+at the same time.
+It's best practice to speak with the stable release manager before
+uploading to stable/stable-proposed-updates, so that the
+uploaded package fits the needs of the next point release.
-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.
+Please see the information in the
-To upload a package, you need a personal account on
-
-If you want to use the feature described in ,
-you'll have to upload to ftp-master. It is the only upload
-point that supports delayed incoming.
+To upload a package, you should upload the files (including the signed
+changes and dsc-file) with anonymous ftp to
+
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
-the changes file last, you can simply copy your files to a temporary
-directory on ftp-master and then move them to
-&us-upload-dir;.
-
+all files have been uploaded.
+
+
Note: Do not upload to ftp-master cryptographic
packages which belong to contrib or non-free. Uploads of
such software should go to non-us (see ). Furthermore packages containing code that is
-patent-restricted by the United States government can not be uploaded to
+patent-restricted by the United States government cannot be uploaded to
ftp-master; depending on the case they may still be uploaded to
You may also find the Debian packages or
useful
-when uploading packages. These handy programs help automate the
+when uploading packages. These handy programs help automate the
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
-
-You can check your upload the same way it's done on ftp-master,
-with:
-
Note that U.S. residents or citizens are subject to restrictions on
export of cryptographic software. As of this writing, U.S. citizens
@@ -1835,64 +1847,50 @@ 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
-Note: Do not upload packages containing software that is
-export-controlled by the United States government to the queue on
-chiark. Since this upload queue goes to ftp-master, the
-prescription found in applies here as well.
-
-The program
-Another upload queue is available in Germany: just upload the files
-via anonymous FTP to
-The upload must be a complete Debian upload, as you would put it into
-ftp-master's
-There's no need to move your files into a second directory after the
-upload, as on chiark. And, in any case, you should get a
-mail reply from the queue daemon explaining what happened to your
-upload. Hopefully it should have been moved to ftp-master, but in
-case of errors you're notified, too.
+With a fairly recent dput, this section
+
-Note: Do not upload packages containing software that is
-export-controlled by the United States government to the queue on
-erlangen. Since this upload queue goes to ftp-master, the
+Note:
+Since this upload queue goes to ftp-master, the
prescription found in applies here as well.
-
-The program
+Do NOT upload a package to the security upload queue (oldstable-security,
+stable-security, etc.) without prior authorization from the security
+team. If the package does not exactly meet the team's requirements, it
+will cause many problems and delays in dealing with the unwanted upload.
+For details, please see section .
-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
-upload files, just as in erlangen, to
-An upload queue is available in Japan: just upload the files via
-anonymous FTP to
+The queues on master.debian.org, samosa.debian.org, master.debian.or.jp,
+and ftp.chiark.greenend.org.uk are down permanently, and will not be
+resurrected. The queue in Japan will be replaced with a new queue on
+hp.debian.or.jp some day.
+
+For the time being, the anonymous ftp queue on auric.debian.org (the
+former ftp-master) works, but it is deprecated and will be removed at
+some point in the future.
-Note also that if you upload via queues, the queue daemon software will
+Note that if you upload via queues, the queue daemon software will
also send you a notification by email.
-
The
-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, .
+Note that the Section field describes both the section as
+well as the subsection, which are described in . If the section is "main", it should be
+omitted. The list of allowable subsections can be found in
-The bug tracking system's features interesting to developers are described
+The bug tracking system's features are described
in the
Operations such as reassigning bugs to other packages, merging separate
bug reports about the same issue, or reopening bugs when they are
@@ -2024,7 +2024,7 @@ 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
+other packages. The bug tracking system's features
are described in the
-Filing bugs for problems that you find in other packages is one of
+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.
@@ -2048,7 +2048,7 @@ to the good documentation and so on). If the same report comes up
again and again you may ask yourself if the documentation is good
enough or if the program shouldn't detect its misuse in order to
give an informative error message. This is an issue that may need
-to be brought to the upstream author.
+to be brought up with the upstream author.
If the bug submitter disagrees with your decision to close the bug,
they may reopen it until you find an agreement on how to handle it.
@@ -2062,9 +2062,8 @@ doing so, please read the
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
@@ -2072,6 +2071,17 @@ 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 an upload is identified as
If you happen to mistype a bug number or forget a bug in the changelog
entries, don't hesitate to undo any damage the error caused. To reopen
wrongly closed bugs, send an reopen XXX command to
@@ -2171,8 +2192,10 @@ 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; as soon as possible. Useful information
-includes, for example:
+&email-security-team; as soon as possible. DO NOT UPLOAD any
+packages for stable; the security team will do that.
+
+Useful information includes, for example:
-There are a few ways a developer can learn of a security problem:
+There are a few ways developers can learn of a security problem:
+Do NOT include any changes in your package which are
+not directly related to fixing the vulnerability. These will only
+need to be reverted, and this wastes time. If there are other bugs in
+your package that you would like to fix, make an upload to
+proposed-updates in the usual way, after the security advisory is
+issued. The security update mechanism is not a means for introducing
+changes to your package which would otherwise be rejected from the
+stable release, so please do not attempt to do this.
+
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:
+Be sure to verify the following items:
Sometimes a package will change its section. For instance, a
package from the `non-free' section might be GPL'd in a later version,
-in which case, the package should be moved to `main' or
+in which case the package should be moved to `main' or
`contrib'.
-If the package is especially crucial to Debian, you should instead submit
+If you just intend to give the package away, but you can keep maintainership
+for the moment, then you should instead submit
a bug against
-Read instructions on the
@@ -2599,9 +2634,9 @@ porters, and make their jobs unnecessarily difficult.
The first and most important thing is to respond quickly to bug or
issues raised by porters. Please treat porters with courtesy, as if
-they were in fact co-maintainers of your package (which in a way, they
-are). Please be tolerant of succinct or even unclear bug reports,
-doing your best to hunt down whatever the problem is.
+they were in fact co-maintainers of your package (which, in a way, they
+are). Please be tolerant of succinct or even unclear bug reports;
+do your best to hunt down whatever the problem is.
By far, most of the problems encountered by porters are caused by
packaging bugs in the source packages. Here is a checklist
@@ -2649,7 +2684,7 @@ or programs. For instance, you should never be calling programs in
being setup in a special way. Try building your package on another
machine, even if it's the same architecture.
+If you are working on a Debian machine for your porting efforts and you
+need to sign your upload locally for its acceptance in the archive, you
+can run
+You have to make sure that your binary-only NMU doesn't render the package
+uninstallable. This could happen when a source package generates
+arch-dependent and arch-independent packages that depend on each other via
+$(Source-Version).
+
+Despite the
required modification of the changelog, these are called binary-only NMUs
— there is no need in this case to trigger all other architectures
to consider themselves out of date or requiring recompilation.
@@ -2711,6 +2759,10 @@ 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''.
+
+Similar to initial porter uploads, the correct way of invoking
+
-However, if you are a porter doing an NMU for `unstable', the above
+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
@@ -2740,6 +2786,8 @@ 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.)
+For uploads to stable or testing, please coordinate with the appropriate
+release team first.
Secondly, porters doing source NMUs should make sure that the bug they
submit to the BTS should be of severity `serious' or greater. This
@@ -2751,7 +2799,7 @@ 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
+compiler 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.
@@ -2827,86 +2875,51 @@ distributions quickly.
Under certain circumstances it is necessary for someone other than the
-official package maintainer to make a release of a package. This is
+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 developer needs to fix another developer's 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
+This section handles only source NMUs, i.e. NMUs which upload a new
+version of the package. For binary-only NMUs by porters or QA members,
+please see .
+If a buildd builds and uploads a package,
+that too is strictly speaking a binary NMU.
+See for some more information.
+
+The main reason why NMUs are done is when a
+developer needs to fix another developer's packages in order to
+address serious problems or crippling bugs
+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.
-
-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.
-
-
-
-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.
+And please remember the Hippocratic Oath: "Above all, do no harm."
+It is better if a package has an grave bug open, than if a not working
+patch was applied, and the bug is only hidden now but not resolved.
-
-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 ).
+NMUs which fix important, serious or higher severity bugs are encouraged
+and accepted.
+You should endeavor to reach the current maintainer of the package; they
+might be just about to upload a fix for the problem, or have a better
+solution present.
-When a security bug is detected, the security team may do an NMU.
-Please refer to for more information.
+NMUs should be made to assist a package's maintainer in resolving bugs.
+Maintainers should be thankful for that help, and NMUers should respect
+the decisions of maintainers, and try to personally help the maintainer by
+their work.
-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:
+A NMU should follow all conventions, written down in this section.
+For an upload to testing or unstable, this order of steps is recommended:
-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, their upload is
-automatically a source NMU and is subject to its rules. If a porter is
-simply uploading a recompiled binary package, the rules are different;
-see .
+For the testing distribution, the rules may be changed by the release
+managers. Please take additional care, and acknowledge that the usual way
+for a package to enter testing is through unstable.
-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.
+For the stable distribution, please take extra care. Of course, the release
+managers may also change the rules here. Please verify before upload that
+all your changes are OK for inclusion into the next stable release by the
+release manager.
+
+When a security bug is detected, the security team may do an NMU, using
+their own rules. Please refer to for more
+information.
+
+For the differences for Porters NMUs, please see
+.
+
+Of course, it is always possible to agree on special rules with a maintainer
+(like the maintainer asking "please upload this fix directly for me, and no
+diff required").
-
Whenever you have made a change to a package, no matter how trivial,
the version number needs to change. This enables our packing system
@@ -2990,9 +3006,13 @@ 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'.
+
+If you upload a package to testing or stable, sometimes, you need to
+"fork" the version number tree. For this, version numbers like
+1.1-3sarge0.1 could be used.
-
A non-maintainer doing a source NMU must create a changelog entry,
@@ -3007,7 +3027,7 @@ 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
@@ -3024,7 +3044,7 @@ 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.
+maintainer or the original bug submitter 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:
@@ -3035,9 +3055,11 @@ 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.
+Also, after doing an NMU, you have to send
+that information to the existing bugs that are fixed by your NMU,
+including the unified diff.
+Alternatively you can open a new bug and include a
+patch showing all the changes you have made.
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.
@@ -3049,7 +3071,7 @@ 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 , follow the other
@@ -3065,8 +3087,11 @@ changes file.
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
+have to close the bugs that have been tagged fixed by the NMU. The easiest
+way is to use the -v option of
@@ -3078,6 +3103,58 @@ ask them if they would be interested in helping you on a more frequent
basis as co-maintainer or backup maintainer
(see ).
+
-
-
-
@@ -2316,21 +2339,32 @@ 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.
-