X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=ba883c6d21fb2079c1afdafc875fa83f53ec4a2a;hp=1fdd1801eabc9deaf3c01b6e6515f66238f48d33;hb=e4285cf6103cd328a1f5485f3e6db2a88a2605a2;hpb=c8b11816a28e1add890c455142591ccb3e2fb3b8
diff --git a/developers-reference.sgml b/developers-reference.sgml
index 1fdd180..ba883c6 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
%commondata;
-
+
There are two types of Debian packages, namely source and
binary packages.
-Source packages consist of either two or three files: a .dsc
-file, and either a .tar.gz file or both an
-.orig.tar.gz and a .diff.gz file.
+Source packages consist of either two or three files: a .dsc
+file, and either a .tar.gz file or both an
+.orig.tar.gz and a .diff.gz file.
If a package is developed specially for Debian and is not distributed
-outside of Debian, there is just one .tar.gz file which
+outside of Debian, there is just one .tar.gz file which
contains the sources of the program. If a package is distributed
-elsewhere too, the .orig.tar.gz file stores the so-called
+elsewhere too, the .orig.tar.gz file stores the so-called
upstream source code, that is the source code that's
distributed from the upstream maintainer (often the author of
-the software). In this case, the .diff.gz contains the
+the software). In this case, the .diff.gz contains the
changes made by the Debian maintainer.
-The .dsc lists all the files in the source package together
+The .dsc file lists all the files in the source package together
with checksums (md5sums) and some additional info about
the package (maintainer, version, etc.).
@@ -732,28 +776,28 @@ the package (maintainer, version, etc.).
The directory system described in the previous chapter is itself
contained within distribution directories. Each
-distribution is actually contained in the pool directory in the
+distribution is actually contained in the pool directory in the
top-level of the Debian archive itself.
To summarize, the Debian archive has a root directory within an FTP
server. For instance, at the mirror site,
ftp.us.debian.org, the Debian archive itself is
contained in /debian, which is a common location
-(another is /pub/debian).
+(another is /pub/debian).
A distribution is comprised of Debian source and binary packages, and the
-respective Sources and Packages index files, containing
+respective Sources and Packages index files, containing
the header information from all those packages. The former are kept in the
-pool/ directory, while the latter are kept in the dists/
-directory of the archive (because of backwards compatibility).
+pool/ directory, while the latter are kept in the dists/
+directory of the archive (for backwards compatibility).
Stable, testing, and unstable
There are always distributions called stable (residing in
-dists/stable), one called testing (residing in
-dists/testing), and one called unstable (residing in
-dists/unstable). This reflects the development process of the
+dists/stable), one called testing (residing in
+dists/testing), and one called unstable (residing in
+dists/unstable). This reflects the development process of the
Debian project.
Active development is done in the unstable distribution
@@ -793,8 +837,8 @@ stable distribution is updated every now and then. However, these
updates are tested very carefully and have to be introduced into the
archive individually to reduce the risk of introducing new bugs. You
can find proposed additions to stable in the
-proposed-updates directory. Those packages in
-proposed-updates that pass muster are periodically moved as a
+proposed-updates directory. Those packages in
+proposed-updates that pass muster are periodically moved as a
batch into the stable distribution and the revision level of the
stable distribution is incremented (e.g., ‘3.0’ becomes
‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and
@@ -891,16 +935,16 @@ installing them in the Debian archive. It consists of a set of
directories and scripts that are installed both on &ftp-master-host;
and &non-us-host;.
-Packages are uploaded by all the maintainers into an unchecked
+Packages are uploaded by all the maintainers into an unchecked
directory. This directory is scanned every 15 minutes by the katie script
that verifies the integrity of the package and the cryptographic
signature. If the package is considered ready to be installed, it
-is moved into an accepted directory. If it is the first upload of
-the package then it is moved in a new directory waiting an
+is moved into an accepted directory. If it is the first upload of
+the package then it is moved in a new directory waiting an
approval of the ftpmasters. If the package contains files to be installed
-"by-hand" is is moved in the byhand directory waiting a manual
+"by-hand" is is moved in the byhand directory waiting a manual
installation by the ftpmasters. Otherwise, if any error has been detected,
-the package is refused and is moved in the reject directory.
+the package is refused and is moved in the reject directory.
Once the package is accepted the system sends a confirmation
mail to the maintainer, closes all the bugs marked as fixed by the upload
@@ -910,46 +954,45 @@ such URL for packages in the non-US archive) until it is really installed
in the Debian archive. This happens only once a day, the package
is then removed from incoming and installed in the pool along with all
the other packages. Once all the other updates (generating new
-Packages and Sources index files for example) have been
+Packages and Sources index files for example) have been
made, a special script is called to ask all the primary mirrors to update
themselves.
-All debian developers have write access to the unchecked
+All debian developers have write access to the unchecked
directory in order to upload their packages, they also have that access
-to the reject directory in order to remove their bad uploads
-or to move some files back in the unchecked directory. But
+to the reject directory in order to remove their bad uploads
+or to move some files back in the unchecked directory. But
all the other directories are only writable by the ftpmasters, that is
why you can not remove an upload once it has been accepted.
Delayed incoming
-The unchecked directory has a special DELAYED
+The unchecked directory has a special DELAYED
subdirectory. It is itself subdivised in nine directories
-called 1-day to 9-day. Packages which are uploaded in
+called 1-day to 9-day. Packages which are uploaded in
one of those directories will be moved in the real unchecked
directory after the corresponding number of days.
This is done by a script that is run each day and which moves the
packages between the directories. Those which are in "1-day" are
-installed in unchecked while the others are moved in the
-adjacent directory (for example, a package in 5-day will
-be moved in 4-day). This feature is particularly useful
+installed in unchecked while the others are moved in the
+adjacent directory (for example, a package in 5-day will
+be moved in 4-day). This feature is particularly useful
for people who are doing non-maintainer uploads. Instead of
waiting before uploading a NMU, it is uploaded as soon as it is
-ready but in one of those DELAYED/x-day directories.
+ready but in one of those DELAYED/x-day directories.
That leaves the corresponding number of days to the maintainer
in order to react and upload himself another fix if he is not
completely satisfied with the NMU. Alternatively he can remove
the NMU by himself.
The use of that delayed feature can be simplified with a bit
-of integration with your upload tool, the following addition to
-the dupload configuration file should be
-considered.
-
+of integration with your upload tool. For instance, if you use
+dupload (see [), you can add this
+snippet to your configuration file:
$delay = ($ENV{DELAY} || 7);
$cfg{'delayed'} = {
- fqdn => "ftp-master.debian.org",
+ fqdn => "&ftp-master-host;",
login => "yourdebianlogin",
incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
visibleuser => "yourdebianlogin",
@@ -959,9 +1002,8 @@ $cfg{'delayed'} = {
method => "scpb"
};
- ]
-dupload can now be used to easily upload a package
-in one of the delayed directories :
+Once you've made that change, dupload can be used to
+easily upload a package in one of the delayed directories:
DELAY=5 dupload --to delayed <changes-file>
@@ -1002,7 +1044,7 @@ the grep-excuses program part of the
devscripts package. It can be easily put in a crontab
to keep someone informed of the progression of his packages in testing.
-The update_excuses file does not always give the precise reason
+The update_excuses file does not always give the precise reason
why the package is refused, one may have to find it by himself by looking
what would break with the inclusion of the package. The gives some more information
@@ -1019,16 +1061,17 @@ contacted, and he will force the inclusion of the packages.
On the web
Each package has several dedicated web pages that contains many
-informations. First http://&packages-host;/<package>
-will let you discover a presentation of each version of the package
-available in the various distributions. It includes its description,
-the dependencies and some links to download the package.
+informations. http://&packages-host;/package-name
+will display each version of the package
+available in the various distributions. The per-version detailed
+information includes the package description,
+the dependencies and links to download the package.
The bug tracking system sorts the bugs by package, you can
watch the bugs of each package at
-http://&bugs-host;/<package>.
+http://&bugs-host;/package-name.
- The madison utility
+ The madison utility
madison is a command-line utility that is available
on both &ftp-master-host; and &non-us-host;. It
@@ -1222,7 +1265,7 @@ more information.
Assuming no one else is already working on your prospective package,
you must then submit a bug report ([) against the
-pseudo package wnpp
+pseudo-package wnpp
describing your plan to create a new package, including, but not
limiting yourself to, a description of the package, the license of the
prospective package and the current URL where it can be downloaded
@@ -1322,7 +1365,7 @@ to emit errors (they will start with E).
For more information on lintian, see ][.
]-
Downgrade the package to the previous version (if one exists) — this
-tests the postrm and prerm scripts.
+tests the postrm and prerm scripts.
-
Remove the package, then reinstall it.
@@ -1331,7 +1374,7 @@ Remove the package, then reinstall it.
Generating the changes file
When a package is uploaded to the Debian FTP archive, it must be
-accompanied by a .changes file, which gives directions to the
+accompanied by a .changes file, which gives directions to the
archive maintainers for its handling. This is usually generated by
dpkg-genchanges during the normal package build process.
@@ -1350,8 +1393,8 @@ id="upload-bugfix">.
The first time a version is uploaded which corresponds to a particular
upstream version, the original source tar file should be uploaded and
-included in the .changes file. Subsequently, this very same
-tar file should be used to build the new diffs and .dsc
+included in the .changes file. Subsequently, this very same
+tar file should be used to build the new diffs and .dsc
files, and will not need to be re-uploaded.
By default, dpkg-genchanges and
@@ -1363,7 +1406,7 @@ may be modified by using -sa to always include it or
If no original source is included in the upload, the original
source tar-file used by dpkg-source when constructing the
-.dsc file and diff to be uploaded must be
+.dsc file and diff to be uploaded must be
byte-for-byte identical with the one already in the archive.
@@ -1433,7 +1476,7 @@ fix.
Uploading to stable
Uploading to stable means that the package will be placed into the
-proposed-updates directory of the Debian archive for further
+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
@@ -1473,17 +1516,17 @@ inclusion.
Uploading to ftp-master
To upload a package, you need a personal account on
-ftp-master.debian.org, which you should have as an
+&ftp-master-host;, which you should have as an
official maintainer. If you use scp or rsync
-to transfer the files, place them into &us-upload-dir;;
+to transfer the files, place them into &us-upload-dir;;
if you use anonymous FTP to upload, place them into
-/pub/UploadQueue/. Please note that you should transfer
+&upload-queue;. Please note that you should transfer
the changes file last. Otherwise, your upload may be rejected because the
archive maintenance software will parse the changes file and see that not
all files have been uploaded. If you don't want to bother with transferring
the changes file last, you can simply copy your files to a temporary
directory on ftp-master and then move them to
-&us-upload-dir;.
+&us-upload-dir;.
Note: Do not upload to ftp-master cryptographic
packages which belong to contrib or non-free. Uploads of
@@ -1491,36 +1534,33 @@ 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
ftp-master; depending on the case they may still be uploaded to
-non-US/non-free (it's in non-free because of distribution issues
+non-US/non-free (it's in non-free because of distribution issues
and not because of the license of the software). If you can't upload it to
ftp-master, then neither can you upload it to the overseas upload
queues on chiark or erlangen. If you are not sure
whether U.S. patent controls or cryptographic controls apply to your
package, post a message to &email-debian-devel; and ask.
]
-You may also find the Debian packages dupload or
-dput useful
-when uploading packages. These handy programs are distributed with
-defaults for uploading via ftp to ftp-master,
-chiark, and erlangen. They can also be configured to
-use ssh or rsync. See , and for more information.
+You may also find the Debian packages [ or
+][ useful
+when uploading packages. These handy programs help automate the
+process of uploading packages into Debian.
]
-After uploading your package, you can check how the archive maintenance
-software will process it by running dinstall on your changes
-file: dinstall -n foo.changes
+After uploading your package, you can check how the archive
+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)
As discussed above, export controlled software should not be uploaded
to ftp-master. Instead, upload the package to
non-us.debian.org, placing the files in
-&non-us-upload-dir; (both [ and ][ can be used also, with the right invocation). By default,
+&non-us-upload-dir; (again, both ][ and ][ can do this for you if invocated properly). By default,
you can use the same account/password that works on
ftp-master. If you use anonymous FTP to upload, place the
-files into /pub/UploadQueue/.
+files into &upload-queue;.
]
You can check your upload the same way it's done on ftp-master,
with:
@@ -1558,7 +1598,7 @@ residents consult a lawyer before doing uploads to non-US.
Uploads via chiark
If you have a slow network connection to ftp-master, there are
-alternatives. One is to upload files to Incoming via a
+alternatives. One is to upload files to Incoming via a
upload queue in Europe on chiark. For details connect to
.
@@ -1578,12 +1618,12 @@ Another upload queue is available in Germany: just upload the files
via anonymous FTP to .
The upload must be a complete Debian upload, as you would put it into
-ftp-master's Incoming, i.e., a .changes files
-along with the other files mentioned in the .changes. The
-queue daemon also checks that the .changes is correctly
+ftp-master's Incoming, i.e., a .changes files
+along with the other files mentioned in the .changes. The
+queue daemon also checks that the .changes is correctly
signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find
their way to ftp-master via this queue. Please also make sure that
-the Maintainer field in the .changes contains
+the Maintainer field in the .changes contains
your e-mail address. The address found there is used for all
replies, just as on ftp-master.
@@ -1622,7 +1662,7 @@ the ``debian-changes'' lists. This is now done automatically by the archive
maintenance software when it runs (usually once a day). You just need to use
a recent dpkg-dev (>= 1.4.1.2). The mail generated by
the archive maintenance software will contain the OpenPGP/GnuPG signed
-.changes files that you uploaded with your package.
+.changes files that you uploaded with your package.
Previously, dupload used to send those announcements, so
please make sure that you configured your dupload not to
send those announcements (check its documentation and look for
@@ -1792,7 +1832,7 @@ carefully on your machine (cf. [).
Double check that your patch doesn't have any unexpected side effects.
Make sure your patch is as small and as non-disruptive as it can be.
]-
-Upload your package to incoming in DELAYED/7-day (cf.
+Upload your package to incoming in DELAYED/7-day (cf.
[), send the final patch to the maintainer via
the BTS, and explain him that he has 7 days to react if he wants to cancel
the NMU.
@@ -1989,7 +2029,9 @@ environment. Within that chrooted environment, install the
build-essential package and any package
dependencies mentioned in Build-Depends and/or
Build-Depends-Indep. Finally, try building your package
-within that chrooted environment.
+within that chrooted environment. These steps can be automated
+by the use of the pbuilder program which is provided by
+the package of the same name.
]
See the for instructions on setting build dependencies.
@@ -2002,7 +2044,7 @@ Manual">. Setting your architecture to ``i386'' is usually incorrect.
Make sure your source package is correct. Do dpkg-source -x
package.dsc to make sure your source package unpacks
properly. Then, in there, try building your package from scratch with
-dpkg-buildpackage.
+dpkg-buildpackage.
-
Make sure you don't ship your source package with the
debian/files or debian/substvars files.
@@ -2260,10 +2302,10 @@ the actual code has evolved into another package (e.g. libfoo12
was removed because libfoo13 supersedes it) or closed if the
software is simply no more part of Debian.
- Removing packages from Incoming
+ Removing packages from Incoming
-In the past, it was possible to remove packages from incoming.
-With the introduction of the New Incoming system this is no longer
+In the past, it was possible to remove packages from incoming.
+However, with the introduction of the new incoming system, this is no longer
possible. Instead, you have to upload a new revision of your package with
a higher version as the package you want to replace. Both versions will be
installed in the archive but only the higher version will actually be
@@ -2298,7 +2340,7 @@ of the message (no, don't use CC:, because that way the message's subject
won't indicate the bug number).
If the package is especially crucial to Debian, you should instead submit
-a bug against wnpp and title it RFA: package --
+a bug against wnpp and title it RFA: package --
short description and set its severity to
important. RFA stands for Request For Adoption.
Definitely copy the message to debian-devel in this case, as described
@@ -2348,10 +2390,10 @@ If you want to be a good maintainer, you should periodically check the
for your
packages. The BTS contains all the open bugs against your packages.
You can check them by browsing this page:
-http://&bugs-host;/yourlogin@debian.org.
+http://&bugs-host;/yourlogin@debian.org.
Maintainers interact with the BTS via email addresses at
-bugs.debian.org. Documentation on available commands can be
+&bugs-host;. Documentation on available commands can be
found at , or, if you have installed the
doc-debian package, you can look at the local files
&file-bts-docs;.
@@ -2394,10 +2436,75 @@ Debian developer experience.
Filing bugs for problems that you find in other packages is one of
the "civic obligations" of maintainership, see [
-for details.
+for details. However handling the bugs on your own packages is
+even more important.
]
-&FIXME;Talk about tags, forwarding bugs, or else break it into
-different sections...
+Here's a list of steps that you may follow to handle a bug report:
+
+ -
+Decide whether the report corresponds to a real bug or not. Sometimes
+users are just calling a program in the wrong way because they haven't
+read the documentation. If you diagnose this, just close the bug with
+enough information to let the user correct his problem (give pointers
+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 informatory error message. This is an issue that may need
+to be brought to the upstream author.
+
+If the bug submitter disagree with your decision to close the bug,
+he may reopen it until you find an agreement on how to handle it.
+If you don't find any, you may want to tag the bug wontfix
+to let people know that the bug exists but that it won't be corrected.
+If this situation is inacceptable, 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).
+
+ -
+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
+be reassigned to, you may either ask for help on &email-debian-devel; or
+reassign it to debian-policy to let them decide which
+package is in fault.
+
+Sometimes you also have to adjust the severity of the bug so that it
+matches our definition of the severity. That's because people tend to
+inflate the severity of bugs to make sure their bugs are fixed quickly.
+Some bugs may even be dropped to wishlist severity when the requested
+change is just cosmetic.
+ -
+The bug submitter may have forgotten to provide some information, in that
+case you have to ask him the information required. You may use the
+moreinfo tag to mark the bug as such. Moreover if you can't
+reproduce the bug, you tag it unreproducible. Anyone who
+can reproduce the bug is then invited to provide more information
+on how to reproduce it. After a few months, if this information has not
+been sent by someone, the bug may be closed.
+
-
+If the bug is related to the packaging, you just fix it. If you are not
+able to fix it yourself, then tag the bug as help. You can
+also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an
+upstream problem, you have to forward it to the upstream author.
+Forwarding a bug is not enough, you have to check at each release if
+the bug has been fixed or not. If it has, you just close it, otherwise
+you have to remind the author about it. If you have the required skills
+you can prepare a patch that fixes the bug and that you send at the
+same time to the author. Make sure to send the patch in the BTS and to
+tag the bug as patch.
+
-
+If you have fixed a bug in your local copy, or if a fix has been
+committed to the CVS repository, you may tag the bug as
+pending to let people know that the bug is corrected and that
+it will be closed with the next upload (add the closes: in
+the changelog). This is particularly useful if you
+are several developers working on the same package.
+
-
+Once a corrected package is availabe in the unstable
+distribution, you can close the bug. This can be done automatically,
+read
[.
+]
When bugs are closed by new uploads
@@ -2433,7 +2540,7 @@ 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
+sufficient to mail the .changes file to
XXX-done@bugs.debian.org, where XXX is your
bug number.
@@ -2462,6 +2569,159 @@ 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
+
+ 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 .
+
+
+
+ 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).
+
+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 functionnalities. The package
+hello-dbs is a simple example that demonstrates how to
+use dbs.
+
+Additionnaly, dbs provides facilities to create the patches and to keep
+track of what they are for.
+
+ 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 diskspace).
+
+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
+
+ &FIXME; Denis Barbier is going to write it.
+
+
+
+ Specific packaging practices
+
+
+
+ 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...
+
+Good practices for library packaging have been grouped in
+.
+
+ Other specific packages
+
+Several subsets of packages have special subpolicies and corresponding
+packaging rules and practices :
+
+ -
+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).
+
-
+Python related packages have their python policy :
+&file-python-policy; (in the python package).
+
-
+Emacs related packages have the .
+
-
+Java related packages have their .
+
-
+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 in the intent 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 manpage.
+It is something that you must have read if you decide to use debconf.
+
+
+
Miscellaenous advice
@@ -2479,6 +2739,12 @@ upstream README, you should include the URL of the
website if there's any. If the package is not yet considered stable
by the author, you may also want to warn the user that the
package is not ready for production use.
+
+Last but not least, since the first user impression is based on
+that description, you should be careful to avoid english
+mistakes. Ensure that you spell check it.
+ispell has a special option (-g) for that :
+ispell -d american -g debian/control
@@ -2518,7 +2784,7 @@ From time to time you may want to check what has been going on
with the bug reports that you submitted. Take this opportunity to
close those that you can't reproduce anymore. To find
out all the bugs you submitted, you just have to visit
-http://&bugs-host;/your-email@your-isp.com.
+http://&bugs-host;/from:<your-email-addr>.
Reporting lots of bugs at once
@@ -2578,14 +2844,16 @@ way of cooperating between a set of related packages, or you may
simply remind someone that a new upstream version is available
and that you need it.
-Whatever the reason, it is a pain to lookup the email address of the
-maintainer of the package that you are interested in. Fortunately, you
-can use a simple email alias : <package>@&packages-host;.
-<package> can be the name of a source or a binary package.
+Looking up the email address of the maintainer for the package can be
+distracting. Fortunately, there is a simple email alias,
+<package>@&packages-host;, which provides a way to
+email the maintainer, whatever their individual email address (or
+addresses) may be. Replace <package> with the name of
+a source or a binary package.
You may also be interested by contacting the persons who are
subscribed to a given source package via [.
-You can do so by using the <package>@&pts-host;
+You can do so by using the <package-name>@&pts-host;
email address.
@@ -2630,12 +2898,12 @@ 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 .deb from the sponsoree. In
+You can not simply upload a binary .deb from the sponsoree. In
theory, you should only ask only for the diff file, and the location of the
original source tarball, and then you should download the source and apply
the diff yourself. In practice, you may want to use the source package
built by your sponsoree. In that case you have to check that he hasn't
-altered the upstream files in the .orig.tar.gz file that he's
+altered the upstream files in the .orig.tar.gz file that he's
providing.
Do not be afraid to write the sponsoree back and point out changes
@@ -2645,11 +2913,11 @@ means being a mentor.
Once the package meets Debian standards, build the package with
dpkg-buildpackage -us -uc and sign it
-with debsign -m your@email.com changes file
+with debsign -m <your-email-addr> <changes-file>
before uploading it to the incoming directory.
-The Maintainer field of the control file and the
-changelog should list the person who did the packaging, i.e. the
+The Maintainer field of the control file and the
+changelog should list the person who did the packaging, i.e. the
sponsoree. The sponsoree will therefore get all the BTS mail about the
package.
@@ -2691,7 +2959,7 @@ endorse any particular tool to the exclusion of a competing tool.
Most of the descriptions of these packages come from the actual
package descriptions themselves. Further information can be found in
the package documentation itself. You can also see more info with the
-command apt-cache show package_name.
+command apt-cache show <package-name>.
@@ -2823,7 +3091,7 @@ The dput package and script does much the same
thing as dupload, but in a different way. It has
some features over dupload, such as the ability to
check the GnuPG signature and checksums before uploading, and the
-possibility of running dinstall in dry-run mode after the
+possibility of running dinstall in dry-run mode after the
upload.
@@ -2851,16 +3119,29 @@ depends. Or, you can test how your package behaves when installed
into a bare base system.
+
+ pbuilder
+
+pbuilder constructs a chrooted system, and builds
+a package inside the chroot. It is very useful to check that
+a package's build-dependencies are correct, and to be sure that
+unnecessary and wrong build dependencies will not exist in the
+resulting package.
+
+
devscripts
devscripts is a package containing a few wrappers
-and tools which you may find helpful for maintaining your Debian
+and tools which are very helpful for maintaining your Debian
packages. Example scripts include debchange and
dch, which manipulate your debian/changelog
file from the command-line, and debuild, which is a
-wrapper around dpkg-buildpackage.
-
+wrapper around dpkg-buildpackage. The bts
+utility is also very helpful to update the state of bug reports on the
+command line, as is uscan to watch for new upstream
+versions of your packages. Check the devscripts(1) manual
+page for a complete list of available scripts.
@@ -2879,7 +3160,7 @@ finalizing a version and listing the package's current bugs.
debget is a package containing a convenient script
which can be helpful in downloading files from the Debian archive.
You can use it to download source packages, for instance (although
-apt-get source package does pretty much the same
+apt-get source <package-name> does pretty much the same
thing).
@@ -2888,7 +3169,7 @@ thing).
alien
dpkg-repack
grep-dctrl
- pbuilder -->
+-->