X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=cd78885b0e1b9888314fbaf39426cd898af8427b;hb=763ab5c55d6a1281396afbe79f3ecc3165f47068;hp=cd1afddb347d697430027bdb87dc2786e2936cea;hpb=8c24b8b229c9942ba4d27829d3a96ad68a6a7759;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index cd1afdd..cd78885 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -4,14 +4,18 @@ %versiondata; %commondata; - - - + + + + + FIXME: "> + ]>

The procedures discussed within include how to become a maintainer (); how to upload new packages (); and how to handle bug reports ().

The resources discussed in this reference include the mailing lists -and servers (); a discussion of the structure of the -Debian archive (); explanation of the different -servers which accept package uploads (); and a -discussion of resources which can help maintainers with the quality of -their packages (). +() and servers (); a +discussion of the structure of the Debian archive (); explanation of the different servers which accept +package uploads (); and a discussion of +resources which can help maintainers with the quality of their +packages ().

It should be clear that this reference does not discuss the technical details of the Debian package nor how to generate Debian packages. @@ -89,13 +96,14 @@ generally agreed-upon best practices. Thus, it is what is called a Applying to Become a Maintainer - Getting started + Getting started

-So, you've read all the documentation, you understand what everything -in the hello example package is for, and you're about to -Debianize your favourite piece of software. How do you actually -become a Debian developer so that your work can be incorporated into -the Project? +So, you've read all the documentation, you've gone through the , +understand what everything in the hello example +package is for, and you're about to Debianize your favourite piece of +software. How do you actually become a Debian developer so that your +work can be incorporated into the Project?

Firstly, subscribe to &email-debian-devel; if you haven't already. Send the word subscribe in the Subject of an email @@ -204,11 +212,6 @@ That document contains instructions on how to put your key on the public key servers. The New Maintainer Group will put your public key on the servers if it isn't already there.

-Due to export restrictions by the United States government some Debian -packages, including gnupg, are located on ftp sites -outside of the United States. You can find the current locations of -those packages at . -

Some countries restrict the use of cryptographic software by their citizens. This need not impede one's activities as a Debian package maintainer however, as it may be perfectly legal to use cryptographic @@ -242,7 +245,7 @@ before actually applying. If you are well prepared, you can save a lot of timer later on. - Debian Mentors + Debian mentors and sponsors

The mailing list &email-debian-mentors; has been set up for novice maintainers who seek help with initial packaging and other @@ -251,11 +254,21 @@ to that list (see for details).

Those who prefer one-on-one help (e.g., via private email) should also post to that list and an experienced developer will volunteer to help. +

+In addition, if you have some packages ready for inclusion in Debian, +but are waiting for your new maintainer application to go through, you +might be able find a sponsor to upload your package for you. Sponsors +are people who are official Debian maintainers, and who are willing to +criticize and upload your packages for you. Sponsorees can request a +sponsors at . +

+If you wish to be a mentor and/or sponsor, more information is +available in . Debian Developer's Duties - Maintaining Your Debian Information + Maintaining your Debian information

There's a LDAP database containing many informations concerning all developers, you can access it at . You can @@ -268,9 +281,9 @@ is not accessible to the public, for more details about this database, please read its online documentation that you can find at .

-You have to keep the information available there up to date. +You have to keep the information available there up-to-date. - Maintaining Your Public Key + Maintaining your public key

Be very careful with your private keys. Do not place them on any public servers or multiuser machines, such as @@ -287,7 +300,13 @@ key extraction routines discussed in apply. You can find a more in-depth discussion of Debian key maintenance in the documentation for the debian-keyring package. - Going On Vacation Gracefully + + Voting +

+&FIXME; + + + Going on vacation gracefully

Most developers take vacations, and usually this means that they can't work for Debian and they can't be reached by email if any problem occurs. @@ -309,7 +328,7 @@ available in the Debian LDAP database and mark yourself as ``on vacation'' (this information is only accessible to debian developers). Don't forget to remove the ``on vacation'' flag when you come back! - Coordination With Upstream Developers + Coordination with upstream developers

A big part of your job as Debian maintainer will be to stay in contact with the upstream developers. Debian users will sometimes report bugs @@ -328,9 +347,9 @@ developers which can be included there, so that you won't have to modify the sources of the next upstream version. Whatever changes you need, always try not to fork from the upstream sources. - Managing Release Critical Bugs + Managing release-critical bugs

-Release Critical Bugs (RCB) are all bugs that have severity +Release-critical bugs (RCB) are all bugs that have severity critical, grave or serious. Those bugs can delay the Debian release and/or can justify the removal of a package at freeze time. That's why @@ -347,35 +366,8 @@ from the QA group may want to do a Non-Maintainer Upload (see usual before they do their NMU if they have seen no recent activity from you in the BTS). - Quality Assurance Effort -

-Even though there is a dedicated group of people for Quality -Assurance, QA duties are not reserved solely for them. You can -participate in this effort by keeping your packages as bug-free as -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 -for help on &email-debian-qa; or &email-debian-devel;). - - Dealing with unreachable maintainers -

-If you notice that a package is lacking maintenance, you should -make sure the maintainer is active and will continue to work on -his packages. Try contacting him yourself. -

-If you do not get a reply after a few weeks you should collect all -useful information about this maintainer. Start by logging into -the -and doing a full search to check whether the maintainer is on vacation -and when he was last seen. Collect any important package names -he maintains and any Release Critical bugs filled against them. -

-Send all this information to &email-debian-qa;, in order to let the -QA people do whatever is needed. - Retiring Gracefully + Retiring

If you choose to leave the Debian project, you should make sure you do the following steps: @@ -391,8 +383,9 @@ emailing to &email-debian-keyring;. - Mailing Lists, Servers, and Other Machines -

+ + Resources for Debian Developers +

In this chapter you will find a very brief road map of the Debian mailing lists, the main Debian servers, and other Debian machines which may be available to you as a developer. @@ -446,6 +439,13 @@ Online archives of mailing lists are available at . + + Documentation +

+&FIXME; + + + Debian servers

Debian servers are well known servers which serve critical functions @@ -482,7 +482,7 @@ full, suspicious activity, or whatever, send an email to

The ftp-master server, ftp-master.debian.org (or auric.debian.org), holds the canonical copy of the Debian -archive (excluding the non-U.S. packages). Generally, package uploads +archive (excluding the non-US packages). Generally, package uploads go to this server; see .

Problems with the Debian FTP archive generally need to be reported as @@ -531,7 +531,16 @@ To request a CVS area, send a request via email to Debian account should own the CVS root area, and why you need it. - Mirrors of Debian servers + The Developers Database +

+The Deverlopers Database, at , is an LDAP +directory for managing Debian developer attributes. You can use this +resource to search the list of Debian developers. For information on +keeping your entry the developer database up-to-date, see . + + + Mirrors of Debian servers

The web and FTP servers have several mirrors available. Please do not put heavy load on the canonical FTP or web servers. Ideally, the @@ -553,7 +562,7 @@ interested in helping Debian. As such, developers generally do not have accounts on these machines. - Other Debian Machines + Other Debian developer machines

There are other Debian machines which may be made available to you. You can use these for Debian-related purposes as you see fit. Please @@ -568,20 +577,18 @@ id="&url-devel-machines;">. - The Debian Archive - - Overview + The Debian archive

-The &debian-formal; distribution consists of a lot of Debian packages +The &debian-formal; distribution consists of a lot of packages (.deb's, currently around &number-of-pkgs;) and a few -additional files (documentation, installation disk images, etc.). +additional files (such documentation and installation disk images).

Here is an example directory tree of a complete Debian archive:

&sample-dist-dirtree;

As you can see, the top-level directory contains two directories, -dists/ and pool/. The latter is a ``pool'' in which the +dists/ and pool/. The latter is a “pool” in which the packages actually are, and which is handled by the archive maintenance database and the accompanying programs. The former contains the distributions, stable, testing and unstable. @@ -608,7 +615,7 @@ The binary-* and source directories are divided further into subsections. - Sections + Sections

The main section of the Debian archive is what makes up the official &debian-formal; distribution. The @@ -621,7 +628,7 @@ Every package in the main section must fully comply with the (DFSG) and with all other policy requirements as described in the . The DFSG is -our definition of ``free software.'' Check out the Debian Policy +our definition of “free software.” Check out the Debian Policy Manual for details.

Packages in the contrib section have to comply with the DFSG, @@ -651,7 +658,7 @@ many on the CD-ROMs as he's allowed to. (Since this varies greatly from vendor to vendor, this job can't be done by the Debian developers.) - Architectures + Architectures

In the first days, the Linux kernel was only available for the Intel i386 (or greater) platforms, and so was Debian. But when Linux became @@ -679,7 +686,7 @@ available at the . - Subsections + Subsections

The sections main, contrib, and non-free are split into subsections to simplify the installation @@ -694,7 +701,7 @@ Note however that with the introduction of package pools (see the top-level will eventually cease to exist. They will be kept in the packages' `Section' header fields, though. - Packages + Packages

There are two types of Debian packages, namely source and binary packages. @@ -717,7 +724,7 @@ with checksums (md5sums) and some additional info about the package (maintainer, version, etc.). - Distribution directories + Distribution directories

The directory system described in the previous chapter is itself contained within distribution directories. Each @@ -737,7 +744,7 @@ the header information from all those packages. The former are kept in the directory of the archive (because of backwards compatibility). - Stable, testing, and unstable + Stable, testing, and unstable

There are always distributions called stable (residing in dists/stable), one called testing (residing in @@ -751,7 +758,7 @@ distribution). Every Debian developer can update his or her packages in this distribution at any time. Thus, the contents of this distribution change from day-to-day. Since no special effort is done to make sure everything in this distribution is working properly, it is -sometimes ``unstable.'' +sometimes literally unstable.

Packages get copied from unstable to testing if they satisfy certain criteria. To get into testing distribution, a @@ -770,7 +777,7 @@ tightened. Packages which are too buggy are removed. No changes are allowed into testing except for bug fixes. After some time has elapsed, depending on progress, the testing distribution goes into a `deep freeze', when no changes are made to it except those -needed for the installation system. This is called a ``test cycle'', +needed for the installation system. This is called a “test cycle”, and it can last up to two weeks. There can be several test cycles, until the distribution is prepared for release, as decided by the release manager. At the end of the last test cycle, the @@ -789,14 +796,14 @@ can find proposed additions to stable in the 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., `1.3' becomes `1.3r1', -`2.0r2' becomes `2.0r3', and so forth). +stable distribution is incremented (e.g., ‘3.0’ becomes ‘3.0r1’, +‘2.2r4’ becomes ‘2.0r5’, and so forth).

Note that development under unstable continues during the -``freeze'' period, since the unstable distribution remains in +freeze period, since the unstable distribution remains in place in parallel with testing. - Experimental + Experimental

The experimental distribution is a specialty distribution. It is not a full distribution in the same sense as `stable' and @@ -835,7 +842,7 @@ An alternative to experimental is to use your personal web space on people.debian.org (klecker.debian.org). - Release code names + Release code names

Every released Debian distribution has a code name: Debian 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0, @@ -873,9 +880,14 @@ symbolic links for stable, testing, and unstable point to the appropriate release directories. - Package uploads + Managing Packages +

+This chapter contains information related to creating, uploading, +maintaining, and porting packages. + + Package uploads - Announcing new packages + New packages

If you want to create a new package for the Debian distribution, you should first check the + Adding an entry to debian/changelog +

+Changes that you make to the package need to be recorded in the +debian/changelog. These changes should provide a concise +description of what was changed, why (if it's in doubt), and note if +any bugs were closed. They also record when the package was +completed. This file will be installed in +/usr/share/doc/package/changelog.Debian.gz, or +/usr/share/doc/package/changelog.gz for native +packages. +

+The debian/changelog file conform to a certain structure, +with a number of different fields. One field of note, the +distribution, is described in . More +information about the structure of this file can be found in +the Debian Policy section titled "debian/changelog". +

+Changelog entries can be used to automatically close Debian bugs when +the package is installed into the archive. See . +

+It is conventional that the changelog entry notating of a package that +contains a new upstream version of the software looks like this: + + * new upstream version + +

+There are tools to help you create entries and finalize the +changelog for release — see +and . - Checking the package prior to upload + + + Checking the package prior to upload

Before you upload your package, you should do basic testing on it. At a minimum, you should try the following activities (you'll need to @@ -959,7 +1004,7 @@ Remove the package, then reinstall it. - Generating the changes file + 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 @@ -977,7 +1022,7 @@ automatically using the Description field, see . - The original source tarball + The original source tarball

The first time a version is uploaded which corresponds to a particular upstream version, the original source tar file should be uploaded and @@ -1001,7 +1046,7 @@ original source should be uploaded, possibly by using the -sa flag. - Picking a distribution + Picking a distribution

The Distribution field, which originates from the first line of the debian/changelog file, indicates which distribution the @@ -1064,7 +1109,7 @@ fix. --> - Uploading to stable + Uploading to stable

Uploading to stable means that the package will be placed into the proposed-updates directory of the Debian archive for further @@ -1102,9 +1147,9 @@ inclusion. - Uploading a package + Uploading a package - Uploading to ftp-master + Uploading to ftp-master

To upload a package, you need a personal account on ftp-master.debian.org, which you should have as an @@ -1120,21 +1165,21 @@ directory on ftp-master and then move them to &us-upload-dir;.

Note: Do not upload to ftp-master packages -containing software that is export-controlled by the United States -government, nor to the overseas upload queues on chiark or -erlangen. This prohibition covers almost all cryptographic -software, and even sometimes software that contains ``hooks'' to -cryptographic software, such as electronic mail readers that support -PGP encryption and authentication. Uploads of such software should go -to non-us (see ). If you are not -sure whether U.S. export controls apply to your package, post a +containing software that is patent-restricted by the United States +government, nor any cryptographic packages which belong to +contrib or non-free. If you can't upload it to +ftp-master, then neither can you upload it to the overseas +upload queues on chiark or erlangen. Uploads of +such software should go to non-us (see ). 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 program are distributed with defaults for uploading via ftp to ftp-master, -chiark, and erlangen. It can also be configured to +chiark, and erlangen. They can also be configured to use ssh or rsync. See , and for more information. @@ -1143,28 +1188,31 @@ 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 - Uploading to non-US (pandora) + Uploading to non-US (pandora)

As discussed above, export controlled software should not be uploaded -to ftp-master. Instead, use scp or rsync -to copy the package to non-us.debian.org, placing -the files in &non-us-upload-dir;. 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/. -

-The program dupload comes with support for uploading to -non-us; please refer to the documentation that comes with -the program for details. +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 invokation). 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/.

You can check your upload the same way it's done on ftp-master, with: dinstall -n foo.changes

Note that U.S. residents or citizens are subject to restrictions on -export of cryptographic software. As of this writing, U.S. citizens are -allowed to export some cryptographic software, subject to notification -rules by the U.S. Department of Commerce. +export of cryptographic software. As of this writing, U.S. citizens +are allowed to export some cryptographic software, subject to +notification rules by the U.S. Department of Commerce. However, this +restriction has been waived for software which is already available +outside the U.S. Therefore, any cryptographic software which belongs +in the main section of the Debian archive and does not depend +on any package outside of main (e.g., does not depend on +anything in non-US/main) can be uploaded to ftp-master +or its queues, described above.

Debian policy does not prevent upload to non-US by U.S. residents or citizens, but care should be taken in doing so. It is recommended that @@ -1172,18 +1220,19 @@ developers take all necessary steps to ensure that they are not breaking current US law by doing an upload to non-US, including consulting a lawyer.

-For packages in non-US main or contrib, developers should at least -follow the . Maintainers of non-US/non-free packages should -further consult these of non-free software. +For packages in non-US/main, non-US/contrib, +developers should at least follow the . Maintainers of +non-US/non-free packages should further consult the of non-free software.

This section is for information only and does not constitute legal advice. Again, it is strongly recommended that U.S. citizens and residents consult a lawyer before doing uploads to non-US. - Uploads via chiark + 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 @@ -1200,7 +1249,7 @@ The program dupload comes with support for uploading to program for details. - Uploads via erlangen + Uploads via erlangen

Another upload queue is available in Germany: just upload the files via anonymous FTP to . @@ -1231,7 +1280,7 @@ The program dupload comes with support for uploading to the program for details. - Other Upload Queues + Other upload queues

Another upload queue is available which is based in the US, and is a good backup when there are problems reaching ftp-master. You can @@ -1243,7 +1292,7 @@ anonymous FTP to . - Announcing package uploads + Announcing package uploads

When a package is uploaded, an announcement should be posted to one of the ``debian-changes'' lists. This is now done automatically by the archive @@ -1266,7 +1315,7 @@ The dupload program is clever enough to determine where the announcement should go, and will automatically mail the announcement to the right list. See . - + Notification that a new package has been installed

The Debian archive maintainers are responsible for handling package @@ -1288,7 +1337,7 @@ The installation notification also includes information on what section the package was inserted into. If there is a disparity, you will receive a separate email notifying you of that. Read on below. - The override file + The override file

The debian/control file's Section and Priority fields do not actually specify where the file will @@ -1319,7 +1368,7 @@ name="dpkg-scanpackages" section="8">, &file-bts-mailing;, and - Non-Maintainer Uploads (NMUs) + Non-Maintainer Uploads (NMUs)

Under certain circumstances it is necessary for someone other than the official package maintainer to make a release of a package. This is @@ -1337,7 +1386,7 @@ 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. - Terminology + Terminology

There are two new terms used throughout this section: ``binary-only NMU'' and ``source NMU''. These terms are used with specific technical @@ -1372,7 +1421,7 @@ we refer to any type of non-maintainer upload NMUs, whether source and binary, or binary-only. - Who can do an NMU + Who can do an NMU

Only official, registered Debian maintainers can do binary or source NMUs. An official maintainer is someone who has their key in the @@ -1383,7 +1432,7 @@ to the Bug Tracking System. Maintainers almost always appreciate quality patches and bug reports. - When to do a source NMU + When to do a source NMU

Guidelines for when to do a source NMU depend on the target distribution, i.e., stable, unstable, or experimental. Porters have @@ -1436,7 +1485,7 @@ id="nmu-guidelines">. - How to do a source NMU + How to do a source NMU

The following applies to porters insofar as they are playing the dual role of being both package bug-fixers and package porters. If a @@ -1455,7 +1504,7 @@ However, aesthetic changes must not be made in a non-maintainer upload. - Source NMU version numbering + Source NMU version numbering

Whenever you have made a change to a package, no matter how trivial, the version number needs to change. This enables our packing system @@ -1495,22 +1544,22 @@ in some way, i.e., if they are doing a source NMU and not a binary NMU. - + Source NMUs must have a new changelog entry

A non-maintainer doing a source NMU must create a changelog entry, describing which bugs are fixed by the NMU, and generally why the NMU was required and what it fixed. The changelog entry will have the non-maintainer's email address in the log entry and the NMU version -number in it.

+number in it.

By convention, source NMU changelog entries start with the line * Non-maintainer upload -

+ - Source NMUs and the Bug Tracking System + Source NMUs and the Bug Tracking System

Maintainers other than the official package maintainer should make as few changes to the package as possible, and they should always send a @@ -1555,7 +1604,7 @@ In addition, the normal maintainer should always retain the entry in the changelog file documenting the non-maintainer upload. - Building source NMUs + Building source NMUs

Source NMU packages are built normally. Pick a distribution using the same rules as found in . Just as described in @@ -1571,7 +1620,7 @@ changes file. - Porting and Being Ported + Porting and Being Ported

Debian supports an ever-increasing number of architectures. Even if you are not a porter, and you don't use any architecture but one, it @@ -1588,7 +1637,7 @@ a recompile for each architecture, which is amounts to &number-of-arches; more builds. - Being Kind to Porters + Being kind to porters

Porters have a difficult and unique task, since they are required to deal with a large volume of packages. Ideally, every source package @@ -1652,14 +1701,14 @@ although you are probably asking for trouble, since different architectures sometimes standardize on different compilers. Make sure your debian/rules contains separate ``binary-arch'' and -``binary-indep'' targets, as the Debian Packaging Manual requires. +``binary-indep'' targets, as the Debian Policy Manual requires. Make sure that both targets work independently, that is, that you can call the target without having called the other before. To test this, try to run dpkg-buildpackage -b. - Guidelines for Porter Uploads + Guidelines for porter uploads

If the package builds out of the box for the architecture to be ported to, you are in luck and your job is easy. This section applies to @@ -1679,8 +1728,8 @@ set porter-email to your email address. This will do a binary-only build of only the architecture-dependant portions of the package, using the `binary-arch' target in debian/rules. - - Recompilation Binary-Only NMU Versioning + + Recompilation binary-only NMU versioning

Sometimes you need to recompile a package against other packages which have been updated, such as libraries. You do have to bump the version @@ -1704,7 +1753,7 @@ latest version was ``3.4-2.1'', your NMU should have a version number of ``3.4-2.1.1''. - + When to do a source NMU if you are a porter

Porters doing a source NMU generally follow the guidelines found in @@ -1753,14 +1802,14 @@ the waiting period. Of course, such locations have no official blessing or status, so buyer, beware. - Tools for Porters + Tools for porters

There are several tools available for the porting effort. This section contains a brief introduction to these tools; see the package documentation or references for full information. - + quinn-diff

quinn-diff is used to locate the differences from @@ -1769,7 +1818,7 @@ packages need to be ported for architecture Y, based on architecture X. - + buildd

The buildd system is used as a distributed, @@ -1801,7 +1850,7 @@ bounds checking). It will also enable Debian to recompile entire distributions quickly. - + dpkg-cross

dpkg-cross is a tool for installing libraries and @@ -1813,7 +1862,7 @@ enhanced to support cross-compiling. - + Moving, Removing, Renaming, Adopting, and Orphaning Packages

@@ -1822,7 +1871,7 @@ upload process. These procedures should be manually followed by maintainers. This chapter gives guidelines in what to do in these cases. - Moving packages + Moving packages

Sometimes a package will change its section. For instance, a package from the `non-free' section might be GPL'd in a later version, @@ -1849,7 +1898,7 @@ file of the package, and reupload that. Also, you'll need to get the override file updated, as described in . - Removing packages + Removing packages

If for some reason you want to completely remove a package (say, if it is an old compatibility library which is not longer required), you @@ -1864,7 +1913,7 @@ package. When invoked as apt-cache showpkg package, the program will show details for package, including reverse depends. - 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 @@ -1875,7 +1924,7 @@ available in unstable since the previous version will immediately be replaced by the higher. However, if you do proper testing of your packages, the need to replace a package should not occur too often anyway. - Replacing or renaming packages + Replacing or renaming packages

Sometimes you made a mistake naming the package and you need to rename it. In this case, you need to follow a two-step process. First, set @@ -1886,7 +1935,7 @@ that 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. - Orphaning a package + Orphaning a package

If you can no longer maintain a package, you need to inform the others about that, and see that the package is marked as orphaned. @@ -1909,7 +1958,7 @@ case, as described above. Read instructions on the for more information. - Adopting a package + Adopting a package

A list of packages in need of a new maintainer is available at in the Handling Bugs + Handling package bugs - Monitoring bugs + Monitoring bugs

If you want to be a good maintainer, you should periodically check the for your @@ -1959,27 +2008,7 @@ outlining all the open bugs against your packages: Replace address with you official Debian maintainer address. - Submitting Bugs -

-Often as a package maintainer, you find bugs in other packages or else -have bugs reported to your packages which need to be reassigned. The - can tell you how -to do this. -

-We encourage you to file bugs when there are problems. Try to submit -the bug from a normal user account at which you are likely to receive -mail. Do not submit bugs as root. -

-Make sure the bug is not already filed against a package. Try to do a -good job reporting a bug and redirecting it to the proper location. -For extra credit, you can go through other packages, merging bugs -which are reported more than once, or setting bug severities to -`fixed' when they have already been fixed. Note that when you are -neither the bug submitter nor the package maintainer, you should -not actually close the bug (unless you secure permission from the -maintainer). - - Responding to Bugs + Responding to bugs

Make sure that any discussions you have about bugs are sent both to the original submitter of the bug, and the bug itself (e.g., @@ -1989,7 +2018,25 @@ 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 feedback on why the bug was closed. - When bugs are closed by new uploads + Bug housekeeping +

+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 operation of the BTS, such as +how to file, reassign, merge, and tag bugs. 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. +

+&FIXME;Talk about tags, forwarding bugs, or else break it into +different sections... + + + When bugs are closed by new uploads

If you fix a bug in your packages, it is your responsibility as the package maintainer to close the bug when it has been fixed. However, @@ -2026,7 +2073,7 @@ sufficient to mail the .changes file to bug number. - Lintian reports + Lintian reports

You should periodically get the new lintian from `unstable' and check over all your packages. Alternatively you can @@ -2037,7 +2084,37 @@ latest version of the distribution (usually from 'unstable') using the latest lintian. - Reporting lots of bugs at once + + Beyond Packaging +

+Debian is about a lot more than just packaging software and +maintaining those packages. This chapter contains information about +ways, often really critical ways, to contribute to Debian beyond +simply creating and maintaining packages. +

+As a volunteer organization, Debian relies on the discretion of its +members in choosing what they want to work on, and choosing what is +the most critical thing to spend their time on. + + + Bug Reporting +

+We encourage you to file bugs as you find them in Debian packages. +

+Try to submit +the bug from a normal user account at which you are likely to receive +mail. Do not submit bugs as root. +

+Make sure the bug is not already filed against a package. Try to do a +good job reporting a bug and redirecting it to the proper location. +For extra credit, you can go through other packages, merging bugs +which are reported more than once, or setting bug severities to +`fixed' when they have already been fixed. Note that when you are +neither the bug submitter nor the package maintainer, you should +not actually close the bug (unless you secure permission from the +maintainer). + + Reporting lots of bugs at once

Reporting a great number of bugs for the same problem on a great number of different packages &mdash i.e., more than 10 &mdash is a deprecated @@ -2059,19 +2136,56 @@ that the bug report is not forwarded to the bug distribution mailing list. - - Interaction with Prospective Developers + Quality Assurance effort +

+Even though there is a dedicated group of people for Quality +Assurance, QA duties are not reserved solely for them. You can +participate in this effort by keeping your packages as bug-free as +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 +for help on &email-debian-qa; or &email-debian-devel;). + + Dealing with unreachable maintainers +

+If you notice that a package is lacking maintenance, you should +make sure the maintainer is active and will continue to work on +his packages. Try contacting him yourself. +

+If you do not get a reply after a few weeks you should collect all +useful information about this maintainer. Start by logging into +the +and doing a full search to check whether the maintainer is on vacation +and when he was last seen. Collect any important package names +he maintains and any Release Critical bugs filled against them. +

+Send all this information to &email-debian-qa;, in order to let the +QA people do whatever is needed. + + + + + Interacting with prospective Debian developers

-This chapter describes procedures that existing Debian developers should -follow when it comes to dealing with wannabe developers. +Debian's success depends on it's ability to attract and retain new and +talented volunteers. If you are an experienced developer, we +recommend that you get involved with the process of bringing in new +developers. This section describes how to help new prospective +developers. + - Sponsoring packages + Sponsoring packages

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.

+If you wish to volunteer as a sponsor, you can sign up at . +

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. @@ -2086,21 +2200,22 @@ changelog and the control file, the upload can still be traced to you.

If you are an application manager for a prospective developer, you can also be their sponsor. That way you can also verify the how the applicant is -handling the `Tasks and Skills' part of their application. +handling the 'Tasks and Skills' part of their application. + - Advocating new developers + Advocating new developers

See the page about at the Debian web site. - Handling new maintainer applications + Handling new maintainer applications

Please see at the Debian web site. - Overview of Debian Maintainer Tools + Overview of Debian Maintainer Tools

This section contains a rough overview of the tools available to maintainers. The following is by no means complete or definitive, but @@ -2203,7 +2318,7 @@ favor of debhelper. However, it's not a bug to use

yada is another packaging helper tool. It uses a debian/packages file to auto-generate -debian/rules other necessary files in the +debian/rules and other necessary files in the debian/ subdirectory.

Note that yada is called "essentially unmaintained" @@ -2274,7 +2389,7 @@ The debootstrap package and script allows you to By "base system", we mean the bare minimum of packages required to operate and install the rest of the system.

-Having a system link this can be useful in many ways. For instance, +Having a system like this can be useful in many ways. For instance, you can chroot into it if you want to test your build depends. Or, you can test how your package behaves when installed into a bare base system. @@ -2291,6 +2406,17 @@ file from the command-line, and debuild, which is a wrapper around dpkg-buildpackage. + + + dpkg-dev-el +

+dpkg-dev-el is an Emacs lisp package which provides +assistance when editing some of the files in the debian +directory of your package. For instance, when editing +debian/changelog, there are handy functions for +finalizing a version and listing the package's current bugs. + + debget

@@ -2303,8 +2429,6 @@ thing).