Uploading to stable
Uploading to stable means that the package will be placed into the
-proposed-updates directory of the Debian archive for further
+stable-proposed-updates directory of the Debian archive for further
testing before it is actually included in stable.
Extra care should be taken when uploading to stable. Basically, a
@@ -1500,13 +1554,29 @@ packages (by messing with Provides or shlibs files), possibly making
those other packages uninstallable, is strongly discouraged.
The Release Team (which can be reached at &email-debian-release;) will
-regularly evaluate the uploads in proposed-updates and decide if
+regularly evaluate the uploads in stable-proposed-updates and decide if
your package can be included in stable. Please be clear (and
verbose, if necessary) in your changelog entries for uploads to
stable, because otherwise the package won't be considered for
inclusion.
-
+ Uploading to testing-proposed-updates
+
+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.
Uploading a package
@@ -1548,7 +1618,7 @@ maintenance software will process it by running dinstall
on your changes file: dinstall -n foo.changes.
Note that dput can do this for you automatically.
- Uploading to non-US (pandora)
+ Uploading to non-US
As discussed above, export controlled software should not be uploaded
to ftp-master. Instead, upload the package to
@@ -1794,29 +1864,25 @@ distribution, i.e., stable, unstable, or experimental. Porters have
slightly different rules than non-porters, due to their unique
circumstances (see [).
]
-When a security bug is detected, a fixed package should be uploaded
-as soon as possible. In this case, the Debian security officers get in
-contact with the package maintainer to make sure a fixed package is
-uploaded within a reasonable time (less than 48 hours). If the package
-maintainer cannot provide a fixed package fast enough or if he/she
-cannot be reached in time, a security officer may upload a fixed
-package (i.e., do a source NMU).
+When a security bug is detected, the security team may do an NMU.
+Please refer to [ for more information.
]
During the release cycle (see [), NMUs which fix
serious or higher severity bugs are encouraged and accepted. Even
during this window, however, you should endeavor to reach the current
maintainer of the package; they might be just about to upload a fix
for the problem. As with any source NMU, the guidelines found in ][ need to be followed.
+id="nmu-guidelines"> need to be followed. Special exceptions are made
+for ][.
]
-Bug fixes to unstable by non-maintainers are also acceptable, but only
-as a last resort or with permission. The following protocol should
-be respected to do an NMU:
+Uploading bug fixes to unstable by non-maintainers should only be done
+by following this protocol:
-
-Make sure that the package's bug is in the Debian Bug Tracking System
-(BTS). If not, submit a bug.
+Make sure that the package's bugs that the NMU is meant to address are all
+filed in the Debian Bug Tracking System (BTS).
+If they are not, submit them immediately.
-
Wait a few days the response from the maintainer. If you don't get
any response, you may want to help him by sending the patch that fixes
@@ -1837,7 +1903,15 @@ to cancel the NMU.
Follow what happens, you're responsible for any bug that you introduced
with your NMU. You should probably use
[ (PTS)
to stay informed of the state of the package after your NMU.
- ]
+
+
+At times, the release manager or an organized group of developers can
+announce a certain period of time in which the NMU rules are relaxed.
+This usually involves shortening the period during which one is to wait
+before uploading the fixes, and shortening the DELAYED period. It is
+important to notice that even in these so-called "bug squashing party"
+times, the NMU'er has to file bugs and contact the developer first,
+and act later.
How to do a source NMU
@@ -1885,11 +1959,7 @@ absolutely necessary for someone other than the usual maintainer to
make a release based on a new upstream version then the person making
the release should start with the debian-revision value
`0.1'. The usual maintainer of a package should start their
-debian-revision numbering at `1'. Note that if you do
-this, you'll have to invoke dpkg-buildpackage with the
--sa switch to force the build system to pick up the new
-source package (normally it only looks for Debian revisions of '0' or
-'1' — it's not yet clever enough to know about `0.1').
+debian-revision numbering at `1'.
@@ -1963,7 +2033,7 @@ changes file.
Acknowledging an NMU
-If one of your packages has been NMUed, you have to incorporate the
+If one of your packages has been NMU'ed, you have to incorporate the
changes in your copy of the sources. This is easy, you just have
to apply the patch that has been sent to you. Once this is done, you
have to close the bugs that have been tagged fixed by the NMU. You
@@ -2230,7 +2300,7 @@ enhanced to support cross-compiling.
"Collaborative maintenance" is a term describing the sharing of Debian
package maintenance duties by several people. This collaboration is
-almost a good idea, since it generally results in higher quality and
+almost always a good idea, since it generally results in higher quality and
faster bug fix turnaround time. It is strongly recommended that
packages in which a priority of Standard or which are part of
the base set have co-maintainers.
@@ -2253,7 +2323,11 @@ version control system, such as CVS or
Add the co-maintainer's correct maintainer name and address to the
Uploaders field in the global part of the
-debian/control file.
+debian/control file.
+
+Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>
+
+
-
@@ -2348,10 +2422,21 @@ it. In this case, you need to follow a two-step process. First, set
your debian/control file to replace and conflict with the
obsolete name of the package (see the for details). Once you've uploaded
-that package, and the package has moved into the archive, file a bug
+the package and the package has moved into the archive, file a bug
against ftp.debian.org asking to remove the package with the
obsolete name. Do not forget to properly reassign the package's bugs
at the same time.
+
+At other times, you may make a mistake in constructing your package and
+wish to replace it. The only way to do this is to increase the version
+number and upload a new version. The old version will be expired in
+the usual manner. Note that this applies to each part of your package,
+including the sources: if you wish to replace the upstream source tarball
+of your package, you will need to upload it with a different version. An
+easy possibility is to replace foo_1.00.orig.tar.gz with
+foo_1.00+0.orig.tar.gz. This restriction gives each file
+on the ftp site a unique name, which helps to ensure consistency across the
+mirror network.
Orphaning a package
@@ -2447,6 +2532,12 @@ contact the submitter and to record your mail within the
bug log (that means you don't need to send a copy of the mail to
123@bugs.debian.org).
+Once you've dealt with a bug report (e.g. fixed it), mark it as
+done (close it) by sending an explanation message to
+123-done@bugs.debian.org. If you're fixing a bug by
+changing and uploading the package, you can automate bug closing as
+described in [.
+ ]
You should never close bugs via the bug server close
command sent to &email-bts-control;. If you do so, the original
submitter will not receive any information about why the bug was
@@ -2456,15 +2547,17 @@ 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 document the technical operations of the BTS, such as
-how to file, reassign, merge, and tag bugs. This section contains
+other packages. The bug tracking system's features interesting to developers
+are described in the . Operations such as reassigning, merging, and tagging
+bug reports are described in the . This section contains
some guidelines for managing your own bugs, based on the collective
Debian developer experience.
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 on your own packages is
+for details. However, handling the bugs in your own packages is
even more important.
]
Here's a list of steps that you may follow to handle a bug report:
@@ -2487,9 +2580,8 @@ to let people know that the bug exists but that it won't be corrected.
If this situation is unacceptable, you (or the submitter) may want to
require a decision of the technical committee by reassigning the bug
to tech-ctte (you may use the clone command of
-the BTS if you wish to keep it reported against your package).
-
+the BTS if you wish to keep it reported against your package). Before
+doing so, please read the .
-
If the bug is real but it's caused by another package, just reassign
the bug the right package. If you don't know which package it should
@@ -2534,6 +2626,234 @@ distribution, you can close the bug. This can be done automatically,
read
[.
+ Handling security-related bugs
+ ]
+Due to their sensitive nature, security-related bugs must be handled
+carefully. The Debian Security Team exists to coordinate this
+activity, keeping track of outstanding security problems, helping
+maintainers with security problems or fix them themselves, sending
+security advisories, and maintaining security.debian.org.
+
+
+
+
+ What to do when you learn of a
+ security problem
+
+When you become aware of a security-related bug in a Debian package,
+whether or not you are the maintainer, collect pertinent information
+about the problem, and promptly contact the security team at
+&email-security-team;.
+Useful information includes, for example:
+
+
+ - What versions of the package are known to be affected by the
+ bug. Check each version that is present in a supported Debian
+ release, as well as testing and unstable.
+
+
- The nature of the fix, if any is available (patches are
+ especially helpful)
+
+
- Any fixed packages that you have prepared yourself (send only
+ the .diff.gz and .dsc files)
+
+
- Any information needed for the advisory (see
[)
+
+]
+
+ Confidentiality
+
+Unlike most other activities within Debian, information about security
+issues must sometimes be kept private for a time. Whether this is the
+case depends on the nature of the problem and corresponding fix, and
+whether it is already a matter of public knowledge.
+
+There are a few ways a developer can learn of a security problem:
+
+
+ - he notices it on a public forum (mailing list, web site, etc.)
+
- someone files a bug report
+
- someone informs him via private email
+
+
+ In the first two cases, the information is public and it is important
+ to have a fix as soon as possible. In the last case, however, it
+ might not be public information. In that case there are a few
+ possible options for dealing with the problem:
+
+
+ - if it is a trivial problem (like insecure temporary files)
+ there is no need to keep the problem a secret and a fix should be
+ made and released.
+
+
- if the problem is severe (remotely exploitable, possibility to
+ gain root privileges) it is preferable to share the information with
+ other vendors and coordinate a release. The security team keeps
+ contacts with the various organizations and individuals and can take
+ care of that.
+
+
+
+ In all cases if the person who reports the problem asks to not
+ disclose the information that should be respected, with the obvious
+ exception of informing the security team (make sure you tell the
+ security team that the information can not be disclosed).
+
+
+Please note that if secrecy is needed you can also not upload a fix to
+unstable (or anywhere else), since the changelog and diff information
+for unstable is public.
+
+
+There are two reasons for releasing information even though secrecy is
+requested: the problem has been known for a while, or that the problem
+or exploit has become public.
+
+ Security Advisories
+
+Security advisories are only issued for the current, released stable
+distribution, not for testing or unstable. When released, advisories
+are sent to the &email-debian-security-announce;
+mailing list and posted on .
+Security advisories are written and posted by the security
+team. However they certainly do not mind if a maintainer can supply
+some of the information for them, or write part of the
+text. Information that should be in an advisory includes:
+
+
+ - A description of the problem and its scope, including:
+
+ - The type of problem (privilege escalation, denial of
+ service, etc.)
+
- How it can be exploited
+
- Whether it is remotely or locally exploitable
+
- How the problem was fixed
+
+ - Version numbers of affected packages
+
- Version numbers of fixed packages
+
- Information on where to obtain the updated packages
+
- References to upstream advisories, identifiers, and any other
+ information useful in cross-referencing the vulnerability
+
+
+
+ Preparing packages to address security issues
+
+One way that you can assist the security team in their duties is to
+provide fixed packages suitable for a security advisory for the stable
+Debian release.
+
+ When an update is made to the stable release, care must be taken to
+ avoid changing system behavior or introducing new bugs. In order to
+ do this, make as few changes as possible to fix the bug. Users and
+ administrators rely on the exact behavior of a release once it is
+ made, so any change that is made might break someone's system.
+ This is especially true of libraries: make sure you never change the
+ API or ABI, no matter how small the change.
+
+This means that moving to a new upstream version is not a good
+solution. Instead, the relevant changes should be back-ported to the
+version present in the current stable Debian release. Generally,
+upstream maintainers are willing to help if needed. If not, the
+Debian security team may be able to help.
+
+In some cases, it is not possible to back-port a security fix, for
+example when large amounts of source code need to be modified or
+rewritten. If this happens, it may be necessary to move to a new
+upstream version. However, you must always coordinate that with the
+security team beforehand.
+
+Related to this is another important guideline: always test your
+changes. If you have an exploit available, try it and see if it
+indeed succeeds on the unpatched package and fails on the fixed
+package. Test other, normal actions as well, as sometimes a security
+fix can break seemingly unrelated features in subtle ways.
+
+Review and test your changes as much as possible. Check the
+differences from the previous version repeatedly
+(interdiff and debdiff are useful tools for
+this).
+
+When packaging the fix, keep the following points in mind:
+
+
+ - Make sure you target the right distribution in your
+ debian/changelog. For stable this is stable-security and for
+ testing this is testing-security, and for the previous
+ stable release, this is oldstable-security. Do not target
+ distribution-proposed-updates!
+
+
- Make sure the version number is proper. It must be greater
+ than the current package, but less than package versions in later
+ distributions. If in doubt, test it with dpkg
+ --compare-versions. For testing, there must be
+ a higher version in unstable. If there is none yet (for example,
+ if testing and unstable have the same version) you must upload a
+ new version to unstable first.
+
+
- Do not make source-only uploads if your package has any
+ binary-all packages (do not use the -S option to
+ dpkg-buildpackage). The buildd infrastructure will
+ not build those. This point applies to normal package uploads as
+ well.
+
+
- If the upstream source has been uploaded to
+ security.debian.org before (by a previous security update), build
+ the upload without the upstream source (dpkg-buildpackage
+ -sd). Otherwise, build with full source
+ (dpkg-buildpackage -sa).
+
+
- Be sure to use the exact same *.orig.tar.gz as used in the
+ normal archive, otherwise it is not possible to move the security
+ fix into the main archives later.
+
+
- Be sure, when compiling a package, to compile on a clean
+ system which only has packages installed from the distribution you
+ are building for. If you do not have such a system yourself, you
+ can use a debian.org machine (see
[)
+ or setup a chroot (see ][ and
+ ][).
+]
+
+ Uploading the fixed package
+
+DO NOT upload a package to the security upload queue without
+prior authorization from the security team. If the package does not
+exactly meet the team's requirements, it will cause many problems and
+delays in dealing with the unwanted upload.
+
+DO NOT upload your fix to proposed-updates without
+coordinating with the security team. Packages from
+security.debian.org will be copied into the proposed-updates directory
+automatically. If a package with the same or a higher version number
+is already installed into the archive, the security update will be
+rejected by the archive system. That way, the stable distribution
+will end up without a security update for this package instead.
+
+Once you have created and tested the new package and it has been
+approved by the security team, it needs to be uploaded so that it can
+be installed in the archives. For security uploads, the place to
+upload to is
+ftp://security.debian.org/pub/SecurityUploadQueue/ .
+
+
+Once an upload to the security queue has been accepted, the package
+will automatically be rebuilt for all architectures and stored for
+verification by the security team.
+
+
+Uploads which are waiting for acceptance or verification are only
+accessible by the security team. This is necessary since there might
+be fixes for security problems that cannot be disclosed yet.
+
+
+If a member of the security team accepts a package, it will be
+installed on security.debian.org as well as the proper
+distribution-proposed-updates on ftp-master or in the non-US
+archive.
When bugs are closed by new uploads
@@ -2544,10 +2864,11 @@ been accepted into the Debian archive. Therefore, once you get
notification that your updated package has been installed into the
archive, you can and should close the bug in the BTS.
-If you are using a new version of dpkg-dev and you do
-your changelog entry properly, the archive maintenance software will close
-the bugs automatically. All you have to do is follow a certain syntax in
-your debian/changelog file:
+However, it's possible to avoid having to manually close bugs after the
+upload -- just list the fixed bugs in your debian/changelog
+file, following a certain syntax, and the archive maintenance software
+will close the bugs for you. For example:
+
acme-cannon (3.1415) unstable; urgency=low
@@ -2567,61 +2888,144 @@ The author prefers the closes: #XXX syntax, as
one of the most concise and easiest to integrate with the text of the
changelog.
-If you want to close bugs the old fashioned, manual way, it is usually
-sufficient to mail the .changes file to
+If you happen to mistype a bug number or forget one in the changelog file,
+don't hesitate to undo any damage the error caused. To reopen wrongly closed
+bugs, send an reopen XXX command in the bug tracking
+system's control bot. To close any remaining bugs that were fixed by your
+upload, email the .changes file to
XXX-done@bugs.debian.org, where XXX is your
bug number.
+
+Bear in mind that it is not obligatory to close bugs using the changelog
+like described above -- if you simply want to close bugs that don't have
+anything to do with an upload of yours, do it simply by emailing an
+explanation to XXX-done@bugs.debian.org.
- Lintian reports
-
-You should periodically get the new lintian from
-`unstable' and check over all your packages. Alternatively you can
-check for your maintainer email address at the . That report, which is updated
-automatically, contains lintian reports against the
-latest version of the distribution (usually from 'unstable') using the
-latest lintian.
Best Packaging Practices
-Debian's quality is largely due to its Policy that all packages
-follow. But it's also because we accumulated years of experience
-in packaging; very talented people created great tools to make
-good packages without much troubles.
+Debian's quality is largely due to the , which defines explicit baseline requirements
+which all Debian packages must fulfill. Yet there is also a shared
+history of experience which goes beyond the Debian Policy, an
+accumulatation of years of experience in packaging. Many very
+talented people have created great tools, tools which help you, the
+Debian maintainer, create and maintain excellent packages.
-This chapter provides the best known solutions to common problems
-faced during packaging. It also lists various advice collected on
-several mailing lists. By following them, you will make Debian's quality
-even better.
-
-
- Packaging tools and common cases
+This chapter provides some best practices for Debian developers. All
+recommendations are merely that, and are not requirements or policy.
+These are just some subjective hints, advice and pointers collected
+from Debian developers. Feel free to pick and choose whatever works
+best for you.
+
+
+ Best Practices for debian/rules
+
+The following recommendations apply to the debian/rules
+file. Since debian/rules controls the build process and
+selects the files which go into the package (directly or indirectly),
+it's usually the file maintainers spend the most time on.
Helper scripts
-To help you in your packaging effort, you can use helper scripts.
-The best scripts available are provided by debhelper.
-With dh_make (package dh-make), you can
-generate in a few seconds a package that is mostly ready. However that
-apparent simplicity is hiding many things done by the helper scripts.
-You have to know what is done by them, that's why you are strongly
-encouraged to read the corresponding manual pages, starting with
-debhelper(1). That's required because you'll have to
-understand what is going on to be able to use them wisely and to
-fix bugs in a pretty way.
-
-debhelper is very useful because it lets you follow the latest Debian policy
-without doing many modifications since the changes that can be automated are
-almost always automatically done by a debhelper script. Furthermore it
-offers enough flexibility to be able to use it in conjunction with
-some hand crafted shell invocations within the rules file.
-
-You can however decide to not use any helper script, and still write
-some very good rules file. Many examples are available
-at .
+The rationale for using helper scripts in debian/rules is
+that lets maintainers use and share common logic among many packages.
+Take for instance the question of installing menu entries: you need to
+put the file into /usr/lib/menu, and add commands to the
+maintainer scripts to register and unregister the menu entries. Since
+this is a very common thing for packages to do, why should each
+maintainer rewrite all this on their own, sometimes with bugs? Also,
+supposing the menu directory changed, every package would have to be
+changed.
+
+Helper scripts take care of these issues. Assuming you comply with
+the conventions expected by the helper script, the helper takes care
+of all the details. Changes in policy can be made in the helper
+script, then packages just need to be rebuilt with the new version of
+the helper and no other changes.
+
+[ contains a couple of different helpers. The most
+common and best (in our opinion) helper system is
+debhelper. Previous helper systems, such as
+debmake, were "monolithic": you couldn't pick and
+choose which part of the helper you found useful, but had to use the
+helper to do everything. debhelper, however, is a
+number of seperate little dh_* programs. For instance,
+dh_installman installs and compresses manpages,
+dh_installmenu installs menu files, and so on. Thus, it
+offers enough flexibility to be able to use the little helper scripts,
+where useful, in conjunction with hand-crafted commands in
+debian/rules.
+ ]
+You can get started with debhelper by reading
+, and looking at the examples
+that come with the package. dh_make, from the
+dh-make package (see [), can be
+used to convert a "vanilla" source package to a
+debhelperized package. This shortcut, though,
+should not convince you that you do not need to bother understanding
+the individual dh_* helpers. If you are going to use a
+helper, you do need to take the time to learn to use that helper, to
+learn its expectations and behavior.
+ ]
+Some people feel that vanilla debian/rules files are
+better, since you don't have to learn the intricies of any helper
+system. This decision is completely up to you. Use what works for
+you. Many examples of vanilla debian/rules files are
+available at .
+
+
+
+ Patching source versus patching at build time
+
+Big, complex packages may have many bugs that you need to deal with.
+If you correct a number of bug directly in the source, if you're not
+careful, it can get hard to differentiate the various patches that you
+applied. It can get quite messy when you have to update the package
+to a new upstream version which integrates some of the fixes (but not
+all). You can't take the total set of diffs (e.g., from
+.diff.gz) and work out which patch sets to back out as a
+unit as bugs are fixed upstream.
+
+One good solution is to keep separate patches under the
+debian directory and apply the patches at build time. The
+dbs package provides an convenient means for
+applying patches at build time (and unapplying them at clean time).
+dbs also provides facilities for creating the
+patches and keeping track of what they are for. As always when using
+maintainer tools, you'll have to read the accompanying documentation.
+The package hello-dbs is a simple example that
+demonstrates how to use dbs.
+
+
+ Multiple binary packages
+
+A single source package will often build several binary packages,
+either to provide several flavors of the same software (examples are
+the vim-* packages) or to make several small
+packages instead of a big one (e.g., if the user can install only the
+subset she needs, and thus save some disk space).
+
+The second case can be easily managed in debian/rules.
+You just need to move the appropriate files from the build directory
+into the package's temporary trees. You can do this using
+install (vanilla approach) or dh_install
+(from debhelper). Be sure to check the different
+permutations of the various packages, ensuring that you have the
+inter-package dependancies set right in debian/control.
+
+The first case is a bit more difficult since it involves multiple
+recompiles of the same software but with different configure
+options. The vim is an example of how to manage
+this using an hand-crafted debian/rules file.
+
+
+
+
- Package with multiple patches
-
-Big packages tend to have many upstream bugs that you want to fix within
-the Debian package. If you just correct the bug in the source, all the
-fixes are directly integrated in the .diff.gz file and you
-can't easily differentiate the various patches that you applied. It gets
-very messy when you have to update the package to a new upstream version
-which integrates some of the fixes (but not all).
+
+ Configuration management with debconf
+
-The good solution is to keep separate patches within the
-debian/patches directory and to apply them on the fly at
-build time. The package dbs provides an
-implementation of such a system, you just have to build-depend on dbs to
-be able to use its functionalities. The package
-hello-dbs is a simple example that demonstrates how to
-use dbs.
+Debconf is a configuration management system which
+can be used by all the various packaging scripts
+(postinst mainly) to request feedback from the user
+concerning how to configure the package. Direct user interactions must
+now be avoided in favor of debconf
+interaction. This will enable non-interactive installations in the
+future.
-Additionally, dbs provides facilities to create the patches and to keep
-track of what they are for.
+Debconf is a great tool but it is often poorly used. Many common mistakes
+are listed in the man page.
+It is something that you must read if you decide to use debconf.
+
- Multiple binary packages
-
-A single source package will often build several binary packages, either
-to provide several flavors of the same software (examples are the
-vim-* packages) or to make several small packages instead of a big one
-(it's interesting if the user doesn't need all the packages and can thus
-save some disk space).
-
-The second case can be easily managed by dh_install (from
-debhelper) to move files from the build directory to
-the package's temporary trees.
-
-The first case is a bit more difficult since it involves multiple recompiles
-of the same software but with different configure options. The
-vim is an example of how to manage this with an
-hand crafted rules file.
-
- Handling debconf translations
-
-Like porters, translators have a difficult task. Since they work on many
-packages, they cannot keep track of every change in packages in order to
-be informed when a translated string is outdated. Fortunately
-debconf can automatically report outdated translations,
-if package maintainers follow some basic guidelines described below.
-
-Translators can use debconf-getlang (package
-debconf-utils) to write a templates.xx
-file containing both English and localized fields (where xx is
-the language code, may be followed by a country code). This file can be
-put into the debian subdirectory without any change.
-
-When building a binary package, debian/templates.xx files are
-merged along with debian/templates to generate the
-templates file contained in the binary package. This is
-automatically done by dh_installdebconf (package
-debhelper). If you do not use debhelper, you can
-do the same with debconf-mergetemplate
-(package debconf-utils).
-
-When the package maintainer needs to update the templates file, they only
-change debian/templates. When English strings in this file
-and in debian/templates.xx differ, translators do know that
-their translation is outdated.
-
-Please see the page about
-
-at the Debian web site, it contains more detailed instructions, including a
-full example.
+
+ Internationalization
+
+ Handling debconf translations
+
+Like porters, translators have a difficult task. They work on many
+packages and must collaborate with many different
+maintainers. Moreover, most of the time, they are not native English
+speakers, so you may need to be particularly patient with them.
+
+The goal of debconf was to make packages
+configuration easier for maintainers and for users. Originally,
+translation of debconf templates was handled with
+debconf-mergetemplate. However, that technique is now
+deprecated; the best way to accomplish debconf
+internationalization is by using the po-debconf
+package. This method is easier both for maintainer and translators;
+transition scripts are provided.
+
+Using po-debconf, the translation is stored in
+po files (drawing from gettext translation
+techniques). Special template files contain the original messages and
+mark which fields are translatable. When you change the value of a
+translatable field, by calling debconf-updatepo, the
+translation is marked as needing attention from the translators. Then,
+at build time, the dh_installdebconf program takes care
+of all the needed magic to add the template along with the up-to-date
+translations into the binary packages. Refer to the manual page for details.
+
+
+
+ Internationalized Documentation
+
+Internationalizing documentation is crucial for users, but a lot of
+labor. There's no way to eliminate all that work, but you can make things
+easier for translators.
+
+If you maintain documentation of any size, its easier for translators
+if they have access to a source control system. That lets translators
+see the differences between two versions of the documentation, so, for
+instance, they can see what needs to be retranslated. It is
+recommended that the translated documentation maintain a note about
+what source control revision the translation is based on. An
+interesting system is provided by in the boot-floppies package,
+which shows an overview of the translation status for any given
+language, using structured comments for the current revision of the
+file to be translated and, for a translated file, the revision of the
+original file the translation is based on. You might wish to adapt
+and provide that in your CVS area.
+
+If you maintain XML or SGML documentation, we suggest that you isolate
+any language-independant information and define those as entities in a
+separate file which is included by all the different
+translations. This makes it much easier, for instance, to keep URLs
+up-to-date across multiple files.
+
+
-
- Specific packaging practices
+
+ Common Situations
+
+ Packages using
+ autoconf/automake
+
+Keeping autoconf's config.sub and
+config.guess files up-to-date is critical for porters,
+especially on more volatile architectures. Some very good packaging
+practices for any package using autoconf and/or
+automake have been synthesized in
+&file-bpp-autotools;. You're strongly encouraged to read this file and
+to follow the given recommendations.
+
+
Libraries
Libraries are always difficult to package for various reasons. The policy
imposes many constraints to ease their maintenance and to make sure
upgrades are as simple as possible when a new upstream version comes out.
-A breakage in a library can result in dozens of dependent packages to
-break...
+A breakage in a library can result in dozens of dependent packages
+breaking.
Good practices for library packaging have been grouped in
.
- Other specific packages
+ Other specific packages
Several subsets of packages have special sub-policies and corresponding
packaging rules and practices:
-
-Perl related packages have a ,
+Perl related packages have a ,
some examples of packages following that policy are
libdbd-pg-perl (binary perl module) or
libmldbm-perl (arch independent perl module).
@@ -2743,25 +3167,12 @@ name="emacs policy">.
Java related packages have their .
-
-Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in
+Ocaml related packages have their Ocaml policy: &file-ocaml-policy; (in
the ocaml package). A good example is the camlzip
source package.
-
-
- Configuration management
-
- The wise use of debconf
-
-Debconf is a configuration management system, it is used by all the
-various packaging scripts (postinst mainly) to request feedback from the
-user concerning how to configure the package. Direct user interactions
-must now be avoided in favor of debconf interaction. This will enable
-non-interactive installations in the future.
-
-Debconf is a great tool but it is often badly used ... many common mistakes
-are listed in the man page.
-It is something that you must read if you decide to use debconf.
+
+