X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=d9b32af5d320e7f2ac8c2b74e5b12760c5aca8e2;hb=29d894ef84ae1a1583cfa162475c7c5a36bea9c9;hp=07be5f87550db3ce0c2a54a9337e69576fc98858;hpb=2aa2659c4608b77487e54ff151227373c598247b;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 07be5f8..d9b32af 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,7 +6,7 @@ %commondata; - + @@ -87,7 +87,7 @@ id="&url-debian-policy;" name="Debian Policy Manual">.
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. @@ -116,14 +116,14 @@ 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
@@ -157,7 +157,7 @@ The process of registering as a developer is a process of verifying
your identity and intentions, and checking your technical skills. As
the number of people working on &debian-formal; has grown to over
&number-of-maintainers; people and our systems are used in several
-very important places we have to be careful about being compromised.
+very important places, we have to be careful about being compromised.
Therefore, we need to verify new maintainers before we can give them
accounts on our servers and let them upload packages.
@@ -175,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
@@ -289,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
+Ideally, you should sign up at the
+
-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.
@@ -530,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,
@@ -546,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 mirror to another server.
+is mirrored to another server.
@@ -635,7 +673,7 @@ Problems with the non-US package archive should generally be submitted as
bugs against the
Our CVS server is located on cvs.debian.org.
@@ -731,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
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
@@ -843,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.
@@ -889,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
-
@@ -908,7 +947,7 @@ 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.
@@ -1010,9 +1049,9 @@ 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.
-Please consider to use the option -v to
@@ -1085,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
@@ -1186,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.
@@ -1500,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
@@ -1511,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:
@@ -1731,11 +1786,12 @@ 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.
+
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
-The scp queues on ftp-master, non-us and security are mostly unuseable
+The scp queues on ftp-master, non-us, and security are mostly unusable
due to the login restrictions on those hosts.
The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are
currently down. Work is underway to resurrect those.
-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
+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.
@@ -1858,7 +1914,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.
-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 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
@@ -1968,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.
@@ -1992,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.
@@ -2006,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
@@ -2016,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
@@ -2150,10 +2227,10 @@ 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:
+There are a few ways developers can learn of a security problem:
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'.
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
@@ -2607,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.
@@ -2669,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
@@ -2698,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
@@ -2709,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.
@@ -2785,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
@@ -2948,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,
@@ -2965,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
@@ -2982,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:
@@ -2993,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.
@@ -3007,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
@@ -3023,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
@@ -3036,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 ).
+
+Unless you know the maintainer is still active, it is wise to check the
+package to see if it has been orphaned. The current list of orphaned
+packages which haven't had their maintainer set correctly is available at
+
+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.
+
+
+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: always use ``binary NMU'' or ``binNMU'' for binary-only
+NMUs.
+
Generally there is a primary maintainer and one or more
@@ -3104,8 +3223,8 @@ Please see below for details.
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:
@@ -3113,35 +3232,35 @@ the following:
To find out whether a package is progressing into testing or not, see the
testing script output on the
The
Some further dependency analysis is shown on
-
+
For the testing migration script, "outdated" means: There are different
versions in unstable for the release architectures (except for the
-architectures in fuckedarches; fuckedarches is an list of architectures
+architectures in fuckedarches; fuckedarches is a list of architectures
that don't keep up (in update_out.py), but currently, it's empty).
"outdated" has nothing whatsoever to do with the architectures this package
has in testing.
@@ -3198,9 +3319,9 @@ if you maintain glibc or so.)
Sometimes, a package is removed to allow another package in: This happens
-only to allow _another_ package to go in, that's ready in every other
-sense. Consider e.g. that a conflicts with the new version of b; than a may
-be removed to allow b in.
+only to allow another package to go in if it's ready in every other
+sense. Suppose e.g. that a conflicts with the new version of
+b; then a may be removed to allow b in.
Of course, there is another reason to remove a package from testing: It's
just too buggy (and having a single RC-bug is enough to be in this state).
@@ -3208,23 +3329,23 @@ just too buggy (and having a single RC-bug is enough to be in this state).
-A situation that is not handled very well by britney is if package a
-depends on the new version of package b, and vice versa.
+A situation which is not handled very well by britney is if package a
+depends on the new version of package b, and vice versa.
An example of this is:
-
+
-Package a is not considered for update, and package b also not.
+Neither package a nor package b is considered for update.
-Currently, this requires some manual hinting from the release masters.
-Please, send mail to debian-release@lists.debian.org if that happens to
-one of your packages.
+Currently, this requires some manual hinting from the release team.
+Please contact them by sending mail to &email-debian-release; if this
+happens to one of your packages.
In summary this means: The only influence that a package being in testing
has on a new version of the same package is that the new version might
@@ -3250,17 +3372,17 @@ If you are interested in details, this is how britney works:
The packages are looked at to determine whether they are valid
candidates. This gives the "update excuses". The most common reasons
-why a package is not considered are too young, RC-bugginess and out of
+why a package is not considered are too young, RC-bugginess, and out of
date on some arches. For this part, the release managers have hammers
of any size to force britney to consider a package. (Also, the base
freeze is coded in that part of britney.) (There is a similar thing
for binary-only updates, but this is not described here. If you're
-interessted in that, please use the code.)
+interested in that, please peruse the code.)
Now, the more complex part happens: Britney tries to update testing with
the valid candidates; first, each package alone, and then larger and even
-larger sets of packages together. Each try is accepted if sarge is not
-more uninstallable after the update as before. (Before and after this part,
+larger sets of packages together. Each try is accepted if unstable is not
+more uninstallable after the update than before. (Before and after this part,
some hints are processed; but as only release masters can hint, this is
probably not so important for you.)
@@ -3285,19 +3407,39 @@ upload to testing-proposed-updates.
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;.
+release managers' eyes, you should read the instructions that they regularly
+give 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. Even if a package is
+newer development version in unstable), you may use this facility,
+but it is recommended that you ask for authorization from
+the release manager first.
+Even if a package is
frozen, updates through unstable are possible, if the upload via unstable
-does not pulls an new dependency in.
+does not pull in any new dependencies.
Version numbers are usually selected by adding the codename of the testing
-distribution and a incrementing number, like 1.2sarge1 for the first upload
-through testing-proposed-updates of the package version 1.2.
+distribution and a running number, like 1.2sarge1 for the first upload
+through testing-proposed-updates of package version 1.2.
+
+Please make sure you didn't miss any of these items in your upload:
+
-All bugs of some higher severities are by default considered release-critical; currently, these are critical, grave and serious bugs.
+All bugs of some higher severities are by default considered release-critical; currently, these are critical, grave, and serious bugs.
Such bugs are presumed to have an impact on the chances that the package will be released with the stable release of Debian: in general, if a package has open release-critical bugs filed on it, it won't get into "testing", and consequently won't be released in "stable".
-The "testing" bug count for a package is considered to be roughly the bug count at the last point when the "testing" version equalled the "unstable" version. The bugs tagged woody or sarge will not be counted. Bugs with the sid tag will be counted, though.
+The unstable bug count are all release-critical bugs
+without either any release-tag (such as potato, woody) or with release-tag sid;
+also, only if they are neither fixed nor set to sarge-ignore.
+The "testing" bug count for a package is considered to be roughly
+the bug count of unstable count at the last point
+when the "testing" version equalled the "unstable" version.
+
+This will change post-sarge, as soon as we have versions in the bug tracking system.
-The structure of the distribution archives is such that they can only contain one version of a package; a package is defined by its name. So, when the source package acmefoo is installed into "testing", along with its binary packages acme-foo-bin, acme-bar-bin, libacme-foo1 and libacme-foo-dev, the old version is removed.
+The structure of the distribution archives is such that they can only contain one version of a package; a package is defined by its name. So when the source package acmefoo is installed into "testing", along with its binary packages acme-foo-bin, acme-bar-bin, libacme-foo1 and libacme-foo-dev, the old version is removed.
However, the old version may have provided a binary package with an old soname of a library, such as libacme-foo0. Removing the old acmefoo will remove libacme-foo0, which will break any packages which depend on it.
-Evidently, this mainly affects packages which provide changing sets of binary packages in different versions (in turn, mainly libraries). However, it will also affect packages upon which versioned dependencies have been declared of the ==, <= or << varieties.
+Evidently, this mainly affects packages which provide changing sets of binary packages in different versions (in turn, mainly libraries). However, it will also affect packages upon which versioned dependencies have been declared of the ==, <=, or << varieties.
-When the set of binary packages provided by a source package change in this way, all the packages that depended on the old binaries will have to be updated to depend on the new binaries instead. Because installing such a source package into "testing" breaks all the packages that depended on it in "testing", some care now has to be taken: all the depending packages must be updated and ready to be installed themselves so that they won't be broken, and, once everything is ready, manual intervention by the release manager or an assistant is normally required.
+When the set of binary packages provided by a source package change in this way, all the packages that depended on the old binaries will have to be updated to depend on the new binaries instead. Because installing such a source package into "testing" breaks all the packages that depended on it in "testing", some care has to be taken now: all the depending packages must be updated and ready to be installed themselves so that they won't be broken, and, once everything is ready, manual intervention by the release manager or an assistant is normally required.
If you are having problems with complicated groups of packages like this, contact debian-devel or debian-release for help.
Important news about changes in a package can also be put in NEWS.Debian
files. The news will be displayed by tools like apt-listchanges, before
@@ -3791,7 +3943,7 @@ cron (3.0pl1-74) unstable; urgency=low
functionality provided with that script, please install the new
package.
- -- Steve Greenland <stevegr&debian.org> Sat, 6 Sep 2003 17:15:03 -0500
+ -- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500
The NEWS.Debian file is installed as
@@ -3840,7 +3992,7 @@ the
Keep the maintainer scripts as simple as possible. We suggest you use
pure POSIX shell scripts. Remember, if you do need any bash features,
-the maintainer script must have a bash sh-bang line. POSIX shell or
+the maintainer script must have a bash shebang line. POSIX shell or
Bash are preferred to Perl, since they enable
@@ -3853,7 +4005,7 @@ If you need to check for the existence of a command, you should use
something like
+These guidelines include some writing style and typography
+recommendations, general considerations about debconf usage as well as
+more specific recommendations for some parts of the distribution (for
+instance, the installation system).
+
+
+Since debconf appeared in Debian, it has been widely abused and
+several criticisms received by the Debian distribution come from
+debconf abuse with the need of answering a wide bunch of questions
+before getting any little thing installed.
+
+Keep usage notes to what they belong: the NEWS.Debian, or
+README.Debian file. Only use notes for important notes which may
+directly affect the package usability. Remember that notes will always
+block the install until confirmed or bother the user by email.
+
+Carefully choose the questions priorities in maintainer scripts. See
+
+
+Most Debian package maintainers are not native English speakers. So,
+writing properly phrased templates may not be easy for them.
+
+Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+list. Have your templates proofread.
+
+Badly written templates give a poor image of your package, of your
+work...or even of Debian itself.
+
+Avoid technical jargon as much as possible. If some terms sound common
+to you, they may be impossible to understand for others. If you cannot
+avoid them, try to explain them (use the extended description). When
+doing so, try to balance between verbosity and simplicity.
+
+
+Debconf templates may be translated. Debconf, along with its sister
+package po-debconf offers a simple framework for getting
+templates translated by translation teams or even individuals.
+
+Please use gettext-based templates. Install po-debconf on your
+development system and read its documentation ("man po-debconf" is a
+good start).
+
+Avoid changing templates too often. Changing templates text induces
+more work to translators which will get their translation "fuzzied". If
+you plan changes to your original templates, please contact
+translators. Most active translators are very reactive and getting
+their work included along with your modified templates will save you
+additional uploads. If you use gettext-based templates, the
+translator's name and e-mail addresses are mentioned in the po files
+headers.
+
+If in doubt, you may also contact the translation team for a given
+language (debian-l10n-xxxxx@lists.debian.org), or the
+debian-i18n@lists.debian.org mailing list.
+
+
+Templates text should not make reference to widgets belonging to some
+debconf interfaces. Sentences like "If you answer Yes..." have no
+meaning for users of graphical interfaces which use checkboxes for
+boolean questions.
+
+More generally speaking, try to avoid referring to user actions.
+Just give facts.
+
+
+You should avoid the use of first person ("I will do this..." or "We
+recommend..."). The computer is not a person and the Debconf tempaltes
+do not speak for the Debian developers. You should use neutral
+construction and often the passive form. Those of you who already
+wrote scientific publications, just write your templates like you
+would write a scientific paper.
+
+
+The world is made of men and women. Please use gender-neutral
+constructions in your writing. This is not Political Correctness, this
+is showing respect to all humanity.
+
+
+
+This part gives some information which is mostly taken from the
+
+
+
+Results in a free-form input field that the user can type any string into.
+
+
+Prompts the user for a password. Use this with caution; be aware that
+the password the user enters will be written to debconf's
+database. You should probably clean that value out of the database as
+soon as is possible.
+
+
+A true/false choice. Remember: true/false, NOT YES/NO...
+
+
+A choice between one of a number of values. The choices must be
+specified in a field named 'Choices'. Separate the possible values
+with commas and spaces, like this: Choices: yes, no, maybe
+
+
+Like the select data type, except the user can choose any number of
+
+ items from the choices list (or chose none of them).
+
+
+Rather than being a question per se, this datatype indicates a note
+that can be displayed to the user. It should be used only for
+important notes that the user really should see, since debconf will go
+to great pains to make sure the user sees it; halting the install for
+them to press a key, and even mailing the note to them in some
+cases.
+
+
+This type is now considered obsolete: don't use it.
+
+
+THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.
+
+It has been added to cdebconf, the C version of debconf, first used in
+the Debian Installer.
+
+Please do not use it unless debconf supports it.
+
+This type is designed to handle error message. It is mostly similar to
+the "note" type. Frontends may present it differently (for instance,
+the dialog frontend of cdebconf draws a red screen instead of the
+usual blue one).
+
+
+
+Templates descriptions have two parts: short and extended. The short
+description is in the "Description:" line of the template.
+
+The short description should be kept short (50 characters or so) so
+that it may be accomodated by most debconf interfaces. Keeping it
+short also helps translators, as usually translations tend to end up
+being longer than the original.
+
+The short description should be able to stand on its own. Some
+interfaces do not show the long description by default, or only if the
+user explicitely asks for it or even do not show it at all. Avoid
+things like "What do you want to do?"
+
+The short description does not necessarily have to be a full
+sentence. This is part of the "keep it short and efficient"
+recommendation.
+
+The extended description should not repeat the short description word
+for word. If you can't think up a long description, then first, think
+some more. Post to debian-devel. Ask for help. Take a writing class!
+That extended description is important. If after all that you still
+can't come up with anything, leave it blank.
+
+The extended description should use complete sentences. Paragraphs
+should be kept short for improved readability. Do not mix two ideas
+in the same paragraph but rather use another paragraph.
+
+Don't be too verbose. Some debconf interfaces cannot deal very well
+with descriptions of more than about 20 lines, so try to keep it below
+this limit.
+
+For specific rules depending on templates type (string, boolean,
+etc.), please read below.
+
+
+This field should be used for Select and Multiselect types. It
+contains the possible choices which will be presented to users. These
+choices should be separated by commas.
+
+
+
+This field is optional. It contains the default answer for string,
+select and multiselect templates. For multiselect templates, it may
+contain a comma-separated list of choices.
+
+
+
+
+No specific indication except: use the appropriate type by referring
+to the previous section.
+
+
+Below are specific instructions for properly writing the Description
+(short and extended) depending on the template type.
+
+
+
+
+
+
+If the Choices are likely to change often, please consider using the
+"__Choices" trick. This will split each individual choice into a
+single string, which will considerably help translators for doing
+their work.
+
+
+If the default value, for a "select" template, is likely to vary
+depending on the user language (for instance, if the choice is a
+language choice), please use the "_DefaultChoice" trick.
+
+This special field allow translators to put the most appropriate
+choice according to their own language. It will become the default
+choice when their language is used while your own mentioned Default
+Choice will be used chan using English.
+
+Example, taken from the geneweb package templates:
+
+Note the use of brackets which allow internal comments in debconf
+fields. Also note the use of comments which will show up in files the
+translators will work with.
+
+The comments are needed as the DefaultChoice trick is a bit
+confusing: the translators may put their own choice
+
+
+Do NOT use empty default field. If you don't want to use default
+values, do not use Default at all.
+
+If you use po-debconf (and you SHOULD, see 2.2), consider making this
+field translatable, if you think it may be translated.
+
+If the default value may vary depending on language/country (for
+instance the default value for a language choice), consider using the
+special "_DefaultChoice" type documented in
Keeping
Good practices for library packaging have been grouped in
@@ -4041,6 +4519,7 @@ package.
Lisp packages should register themselves with
-Deborphan is a program helping users to detect which packages can be safely
+Deborphan is a program for helping users to detect which packages can safely be
removed from the system, i.e. the ones that have no packages depending on
them. The default operation is to search only within the libs and oldlibs
sections, to hunt down unused libraries. But when passed the right argument,
it tries to catch other useless packages.
-For example, with --guess-dummy, tries to search all transitional packages
+For example, with --guess-dummy, deborphan tries to search all transitional packages
which were needed for upgrade but which can now safely be removed. For that,
it looks for the string "dummy" or "transitional" in their short
description.
So, when you are creating such a package, please make sure to add this text
-to your short description. If you are looking for example, just run:
+to your short description. If you are looking for examples, just run:
+ There are two kinds of original source tarballs: Pristine source
+ and repackaged upstream source.
+
+The defining characteristic of a pristine source tarball is that the
+.orig.tar.gz file is byte-for-byte identical to a tarball officially
+distributed by the upstream author.
+
+There is no universally accepted guidelines that upstream authors
+follow regarding to the directory structure inside their tarball, but
+
+
+You should upload packages with a pristine source
+tarball if possible, but there are various reasons why it might not be
+possible. This is the case if upstream does not distribute the source
+as gzipped tar at all, or if upstream's tarball contains non-DFSG-free
+material that you must remove before uploading.
+
+In these cases the developer must construct a suitable .orig.tar.gz
+file himself. We refer to such a tarball as a "repackaged upstream
+source". Note that a "repackaged upstream source" is different from a
+Debian-native package. A repackaged source still comes with
+Debian-specific changes in a separate .diff.gz and still has
+a version number composed of <upstream-version> and
+<debian-revision>.
+
+There may be cases where it is desirable to repackage the source even
+though upstream distributes a .tar.gz that could in principle
+be used in its pristine form. The most obvious is if
+significant space savings can be achieved by recompressing
+the tar archive or by removing genuinely useless cruft from the
+upstream archive. Use your own discretion here, but be prepared to
+defend your decision if you repackage source that could have been
+pristine.
+
+A repackaged .orig.tar.gz
+
+
+must contain detailed information how
+the repackaged source was obtained, and how this can be reproduced, in
+
+should, except where impossible for legal reasons,
+preserve the entire building and portablility infrastructure provided
+by the upstream author. For example, it is not a sufficient reason for
+omitting a file that it is used only when building on
+MS-DOS. Similarly, a Makefile provided by upstream should not be
+omitted even if the first thing your
+(Rationale: It is common for Debian users who need to build
+software for non-Debian platforms to fetch the source from a Debian
+mirror rather than trying to locate a canonical upstream distribution
+point).
+
+The canonical way to meet the latter two points is to let
+dpkg-source -b construct the repackaged tarball from an
+unpacked directory.
+
+Sometimes it is necessary to change binary files contained in the
+original tarball, or to add binary files that are not in it.
+If this is done by simply copying the files into the debianized source
+tree,
+Some packages use
Try to direct your bugs to the proper location. When for example
-your bug is about a package that overwrites files from another package,
+your bug is about a package which overwrites files from another package,
check the bug lists for both of those packages in order to
avoid filing duplicate bug reports.
@@ -4194,7 +4865,8 @@ is emitted.
If you report more than 10 bugs on the same topic at once, it is
recommended that you send a message to &email-debian-devel; describing
-your intention before submitting the report. This will allow other
+your intention before submitting the report, and mentioning the
+fact in the subject of your mail. This will allow other
developers to verify that the bug is a real problem. In addition, it
will help prevent a situation in which several maintainers start
filing the same bug report simultaneously.
@@ -4216,7 +4888,7 @@ possible, and as lintian-clean (see ) as
possible. If you do not find that possible, then you should consider
orphaning some of your packages (see ). Alternatively, you may ask the help of other people
-in order to catch up the backlog of bugs that you have (you can ask
+in order to catch up with the backlog of bugs that you have (you can ask
for help on &email-debian-qa; or &email-debian-devel;). At the same
time, you can look for co-maintainers (see ).
@@ -4224,13 +4896,13 @@ time, you can look for co-maintainers (see ).
From time to time the QA group organizes bug squashing parties to get rid of
as many problems as possible. They are announced on &email-debian-devel-announce;
-and the announce explains what area will be focused on during the party:
+and the announcement explains which area will be the focus of the party:
usually they focus on release critical bugs but it may happen that they
-decide to help finish a major upgrade going on (like a new perl version
+decide to help finish a major upgrade (like a new perl version
which requires recompilation of all the binary modules).
The rules for non-maintainer uploads differ during the parties because
-the announce of the party is considered like a prior notice for NMU. If
+the announcement of the party is considered prior notice for NMU. If
you have packages that may be affected by the party (because they have
release critical bugs for example), you should send an update to each of
the corresponding bug to explain their current status and what you expect
@@ -4240,12 +4912,12 @@ the BTS.
People participating in the party have special rules for NMU, they can
NMU without prior notice if they upload their NMU to
-DELAYED/3-day at least. All other NMU rules applies as usually, they
-should send the patch of the NMU in the BTS (in one of the open bugs
-fixed by the NMU or in a new bug tagged fixed). They should
-also respect the maintainer's wishes if he expressed some.
+DELAYED/3-day at least. All other NMU rules apply as usually; they
+should send the patch of the NMU to the BTS (to one of the open bugs
+fixed by the NMU, or to a new bug, tagged fixed). They should
+also respect any particular wishes of the maintainer.
-If someone doesn't feel confident with an NMU, he should just send a patch
+If you don't feel confident about doing an NMU, just send a patch
to the BTS. It's far better than a broken NMU.
@@ -4268,7 +4940,7 @@ You may also be interested in contacting the persons who are
subscribed to a given source package via .
You can do so by using the <package-name>@&pts-host;
email address.
-
+
@@ -4279,9 +4951,9 @@ haven't registered out of the system, so to speak. On the other hand,
it is also possible that they just need a reminder.
There is a simple system (the MIA database) in which information about
-maintainers who are deemed inactive are recorded. When a member of the
+maintainers who are deemed Missing In Action are recorded. When a member of the
QA group contacts an inactive maintainer or finds more information about
-them, this is recorded in the MIA database. This system is available
+one, this is recorded in the MIA database. This system is available
in /org/qa.debian.org/mia on the host qa.debian.org, and can be queried
with a tool known as
The first step is to politely contact the maintainer, and wait for a
-response, for a reasonable time. It is quite hard to define "reasonable
+response for a reasonable time. It is quite hard to define "reasonable
time", but it is important to take into account that real life is sometimes
-very hectic. One way to handle this would be send a reminder after two
+very hectic. One way to handle this would be to send a reminder after two
weeks.
If the maintainer doesn't reply within four weeks (a month), one can
@@ -4305,7 +4977,7 @@ about the maintainer in question as possible. This includes:
On the other hand, although we are volunteers, we do have a responsibility.
@@ -4368,9 +5040,11 @@ Sponsoring a package means uploading a package for a maintainer who is not
able to do it on their own, a new maintainer applicant. Sponsoring a package
also means accepting responsibility for it.
+
New maintainers usually have certain difficulties creating Debian packages
— this is quite understandable. That is why the sponsor is there, to check
the package and verify that it is good enough for inclusion in Debian.
@@ -4393,7 +5067,7 @@ By uploading a sponsored package to Debian, you are certifying that
the package meets minimum Debian standards. That implies that you
must build and test the package on your own system before uploading.
-You can not simply upload a binary
The Maintainer field of the
Debian supports an ever-increasing number of natural languages. Even if you are
-native English speaker and do not speak any other language, it is part of your
+a native English speaker and do not speak any other language, it is part of your
duty as a maintainer to be aware of issues of internationalization (abbreviated
i18n because there are 18 letters between the 'i' and the 'n' in
-internationalization). Therefore, even if you are ok with English only
+internationalization). Therefore, even if you are ok with English-only
programs, you should read most of this chapter.
According to
-Letting alone the i18n problems, where no general receipt exist, there is
+Setting aside the i18n problems, where no general guideline can be given, there is
actually no central infrastructure for l10n within Debian which could be
-compared to the dbuild mechanism for porting. So, most of the work has to be
+compared to the dbuild mechanism for porting. So most of the work has to be
done manually.
@@ -4477,104 +5151,110 @@ translation Project"> or the
-An effort to translate the package descriptions started long ago even if very
-few support is offered by the tools to actually use them (ie, only APT can use
-them, when configured correctly). There is nothing to do for the maintainers,
-and the translators should use the
-For debconf templates, maintainer should use the po-debconf package to ease the
-work of translators, which could use the DDTP to do their work (but French and
+For debconf templates, maintainers should use the po-debconf package to ease the
+work of translators, who could use the DDTP to do their work (but the French and
Brazilian teams don't). Some statistics can be found both on the DDTP site
(about what is actually translated), and on the
For web pages, each l10n team has access to the relevant CVS, and the statistics
are available from the Central Debian translation statistics site.
For general documentation about Debian, the process is more or less the same
-than for the web pages (the translators have an access to the CVS), but there is
+than for the web pages (the translators have access to the CVS), but there are
no statistics pages.
-For package specific documentation (man pages, info document, other formats),
-almost everything have yet to be done. Most notably, the KDE project handles
+For package-specific documentation (man pages, info documents, other formats),
+almost everything remains to be done.
+
+Most notably, the KDE project handles
translation of its documentation in the same way as its program messages.
-Debian specific man pages begin to be handled within a
This is a list of problems that maintainers may face concerning i18n and l10n.
-While reading this, keep in mind that there is no real consensus on those
-points within Debian, and that they are only advices. If you have a better idea
+While reading this, keep in mind that there is no real consensus on these
+points within Debian, and that this is only advice. If you have a better idea
for a given problem, or if you disagree on some points, feel free to provide
your feedback, so that this document can be enhanced.
-
-To translate package description or debconf templates, you have nothing to do,
+To translate package descriptions or debconf templates, you have nothing to do;
the DDTP infrastructure will dispatch the material to translate to volunteers
with no need for interaction from your part.
-For all other material (gettext files, man pages or other documentation), the
-best solution is to put your text somewhere on Internet, and ask on debian-i18n
-for a translation in the different languages. Some translation team members are
+For all other material (gettext files, man pages, or other documentation), the
+best solution is to put your text somewhere on the Internet, and ask on debian-i18n
+for a translation in different languages. Some translation team members are
subscribed to this list, and they will take care of the translation and of the
-reviewing process. Once done, you will get your translated document from them
+reviewing process. Once they are done, you will get your translated document from them
in your mailbox.
-
->From time to time, individuals translate some texts included in your package
-and will ask you for inclusion in the package. This can become problematic if
+From time to time, individuals translate some texts in your package
+and will ask you for inclusion of the translation in the package. This can become problematic if
you are not fluent in the given language. It is a good idea to send the
document to the corresponding l10n mailing list, asking for a review. Once it
has been done, you should feel more confident in the quality of the
-translation, and include it fearlessly into your package.
+translation, and feel safe to include it in your package.
-
-If you have some translations of a given text laying around, each time you
-update the original, you should kindly ask to the previous translator to update
-his/her work to make the translation up to date with regard to the current
-original text. Keep in mind that this task takes time, at least one week to get
+If you have some translations of a given text lying around, each time you
+update the original, you should ask the previous translator to update
+the translation with your new changes.
+Keep in mind that this task takes time; at least one week to get
the update reviewed and all.
-If the translator is unresponsive, you may ask for help to the corresponding
+If the translator is unresponsive, you may ask for help on the corresponding
l10n mailing list. If everything fails, don't forget to put a warning in the
translated document, stating that the translation is somehow outdated, and that
the reader should refer to the original document if possible.
-Avoid removing completely a translation because it is outdated. An old
+Avoid removing a translation completely because it is outdated. Old
documentation is often better than no documentation at all for non-English
-speaker.
+speakers.
-
The best solution may be to mark the bug as "forwarded to upstream", and
forward it to both the previous translator and his/her team (using the
corresponding debian-l10n-XXX mailing list).
+
While reading this, please keep in mind that there is no general procedure
-within Debian concerning those points, and that in any case, you should
+within Debian concerning these points, and that in any case, you should
collaborate with your team and the package maintainer.
-
Choose what you want to translate, make sure that nobody is already working on
it (using your debian-l10n-XXX mailing list), translate it, get it reviewed by
other native speakers on your l10n mailing list, and provide it to the
maintainer of the package (see next point).
-
Make sure your translation is correct (asking for review on your l10n mailing
list) before providing it for inclusion. It will save time for everyone, and
@@ -4582,7 +5262,7 @@ avoid the chaos resulting in having several versions of the same document in
bug reports.
The best solution is to fill a regular bug containing the translation against
-the package. Make sure to use the 'PATCH' tag, and to not use a gravity higher
+the package. Make sure to use the 'PATCH' tag, and to not use a severity higher
than 'wishlist', since the lack of translation never prevented a program from
running.
@@ -4601,7 +5281,7 @@ they don't report the errors they find, nobody will.
-Debian maintainer tools are meant to help convenience developers and
+Debian maintainer tools are meant to aid developers and
free their time for critical tasks. As Larry Wall says, there's more
than one way to do it.
@@ -4624,7 +5304,7 @@ Some people prefer to use high-level package maintenance tools and
some do not. Debian is officially agnostic on this issue; any tool
which gets the job done is fine. Therefore, this section is not meant
to stipulate to anyone which tools they should use or how they should
-go about with their duties of maintainership. Nor is it meant to
+go about their duties of maintainership. Nor is it meant to
endorse any particular tool to the exclusion of a competing tool.
Most of the descriptions of these packages come from the actual
@@ -4641,10 +5321,10 @@ The following tools are pretty much required for any maintainer.
You can find documentation for this package in the
-Many feel that this system should be used for all packages requiring
+Many feel that this system should be used for all packages which require
interactive configuration; see .
You should periodically get the newest
The following tools help automate different maintenance tasks, from
-adding changelog entries or signature lines, looking up bugs in Emacs,
-to making use of the newest and official use of
+adding changelog entries or signature lines and looking up bugs in Emacs
+to making use of the newest and official
-Contains best practices for people maintaining packages that use
+
This utility can make it easy to copy packages from one computer to
-another, or to recreate packages that are installed on your system
-but no longer available elsewhere, or to store the current state of a
+another, or to recreate packages which are installed on your system
+but no longer available elsewhere, or to save the current state of a
package before you upgrade it.
-
@@ -2384,7 +2461,7 @@ cases.
+
+
+
+
+
+
+
+
+
+
+
+
+
+