X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=16732d2ee61ee3d9effdf6f5232b3de9eb51482e;hb=90c9e75afaf1cf7994b255f399474aae07db5bfb;hp=eeb6a26fe64791e71ed43bbd038dc2c8fb1165a8;hpb=48eabefe4e4c1b1ebc426cecf3941bdfa50f4f41;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index eeb6a26..16732d2 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -5,11 +5,12 @@ ]> @@ -37,9 +38,9 @@ General Public License for more details. A copy of the GNU General Public License is available as /usr/doc/copyright/GPL in the Debian GNU/Linux distribution or on the World Wide Web at . You can also obtain it by -writing to the Free Software Foundation, Inc., 59 Temple Place - Suite -330, Boston, MA 02111-1307, USA. +id="http://www.gnu.org/copyleft/gpl.html" name="the GNU website">. +You can also obtain it by writing to the Free Software Foundation, +Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. @@ -78,15 +79,15 @@ Manual">. Getting started

So, you've read all the documentation, you understand what everything -in the Firstly, subscribe to .

@@ -102,12 +103,12 @@ details. The IRC channel Registering as a Debian developer

-Before you decide to work in the Debian Project you have to read the -. Registering as a developer means that you agree with and -pledge to uphold the Debian Social Contract; it is very important that -maintainers are in accord with the essential ideas behind Debian -GNU/Linux. Reading the . Registering as a developer means that +you agree with and pledge to uphold the Debian Social Contract; it is +very important that maintainers are in accord with the essential ideas +behind Debian GNU/Linux. Reading the would also be a good idea.

@@ -178,7 +179,7 @@ tampering. You can do it by executing `pgp -ks If your PGP key isn't on public PGP key servers such as pgp.net, please read the documentation available locally /usr/doc/pgp/keyserv.doc. That document contains -instructions on how to put your key on the public keyservers. +instructions on how to put your key on the public key servers.

Due to export restrictions by the United States government some Debian packages, including PGP, have been moved to an ftp site outside of the @@ -186,10 +187,14 @@ United States. You can find the current locations of those packages on /pub/debian/README.non-US file.

-If you live in a country where use of cryptography even for -authentication is forbidden then please contact us so we can make -special arrangements. This does not apply in France, where I believe -only encryption and not authentication is forbidden. +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 +products for authentication, rather than encryption purposes (as is +the case in France). The Debian Project does not require the use of +cryptography Once you have all your information ready, and your public key is available on public key servers, send a message to @@ -201,7 +206,7 @@ also contain your PGP or RSA public key (extracted using pgp underway) for the database of keys which is distributed from /pub/debian/doc/debian-keyring.tar.gz, or the -debian-keyring package). Please be sure to sign your + Once this information is received and processed, you should be @@ -214,7 +219,7 @@ overworked, and mistakes do occasionally happen. Debian Mentors

There is a mailing list called for details). @@ -237,12 +242,13 @@ unsubscribe to the mailing lists can be found at , or locally in /usr/doc/debian/mailing-lists.txt if you have the -doc-debian package installed. +doc-debian package installed.

-When replying to messages on the mailing list, please do not send a -carbon copy ( In addition, all messages should usually only be sent to one of the following mailing lists: . Cross-posting is -discouraged. +id="http://www.debian.org/MailingLists/subscribe">. Cross-posting +(sending the same message to multiple lists) is discouraged.

. - The master server + The master server +

+The master server, . +

+ +All Debian developers have accounts on +If you find a problem with debian-admin@debian.org. + + The FTP servers +

+ + The WWW servers +

+The main web server, +If you have some Debian-specific information which you want to serve +up on the web, you can do do this by putting material in the +public_html directory under your home directory. You can do +this on either http://www.debian.org/~user-id/ and +http://master.debian.org/~user-id/, respectively. +Please do not put any materials on Debian servers which do +not relate to Debian.

-The master server, . All Debian -developers have accounts on this machine. +If you find a problem with the Debian web server, you should generally +submit a bug against the pseudo-package, +www.debian.org. First check whether or not someone +else has already reported the problem on the . - The FTP servers + The CVS server

+ssh. +

+To request a CVS area, send a request via email to +debian-admin@debian.org. + - The WWW servers + 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 +canonical servers only mirror out to a first tier of mirrors, and all +user access is to the mirrors. This allows Debian to better spread +our bandwidth requirements over several servers and networks. Note +that newer push mirroring techniques ensure that mirrors are as +up-to-date as they can be.

+The main web page listing the available public FTP (and, usually, +HTTP) servers can be found at . More information +concerning mirrors can be found at . This useful page includes +information and tools which can be helpful if you are interested in +setting up your own mirror, either for internal or public access. +

+Note that mirrors are generally run by third-parties who are +interested in helping Debian. As such, developers generally do not +have accounts on these machines. The Debian Archive @@ -302,9 +379,17 @@ main/binary-all/comm/ main/binary-all/devel/ ... main/binary-i386/ -main/binary-m86k/ +main/binary-i386/admin/ +main/binary-i386/base/ + ... +main/binary-m68k +main/binary-m68k/admin/ +main/binary-m68k/base/ ... main/source/ +main/source/admin/ +main/source/base/ + ... main/disks-i386/ main/disks-m68k/ ... @@ -312,14 +397,14 @@ main/disks-m68k/ contrib/ contrib/binary-all/ contrib/binary-i386/ -contrib/binary-m86k/ +contrib/binary-m68k/ ... contrib/source/ non-free/ non-free/binary-all/ non-free/binary-i386/ -non-free/binary-m86k/ +non-free/binary-m68k/ ... non-free/source/ @@ -330,7 +415,7 @@ three directories, namely main, contrib, and

In each section, there is a directory with the source packages (source), a directory for each supported architecture (binary-i386, -binary-m86k, etc.), and a directory for architecture independent +binary-m68k, etc.), and a directory for architecture independent packages (binary-all).

The Sections

-The main section is what makes up the Debian GNU/Linux -distribution. This is because the packages in the other two -sections do not fully comply with all our guidelines. As such, they -are not officially part of Debian. +The main section is what makes up the official Debian +GNU/Linux distribution. This is because the packages in the other +two sections do not fully comply with all our guidelines. As such, +they are not officially part of Debian.

-For example, every package in the main distribution must fully comply +For example, every package in the main section must fully comply with the (DFSG) and with all other policy requirements as described in the (The contains a more exact definition of the three -sections. This is just meant to be an introduction.) +sections. The above discussion is just an introduction.)

The separation of the three sections at the top-level of the archive is important for all people who want to distribute Debian, either via @@ -380,8 +465,8 @@ distribution, for example.

On the other hand, a CD-ROM vendor could easily check the individual package licenses of the packages in Architectures @@ -392,7 +477,8 @@ more and more popular, the kernel was ported to other architectures, too.

The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, M68000 -machines (like Atari and Amiga), MIPS, and PowerPC. +(a.k.a. m68k) machines (like Atari and Amiga), MIPS, and PowerPC +(a.k.a. ppc).

Debian GNU/Linux 1.3 is only available for Intel platforms. Debian 2.0 supports Intel and m68k architectures. The next version of Debian @@ -403,8 +489,8 @@ more. Subsections

The sections Source packages consist of either two or three files: a If a package is developed specially for Debian and is not distributed @@ -427,11 +513,11 @@ the sources of the program.

If a package is distributed elsewhere too, the -The The ``development'' is done in the -After about a period of development, the -Note, that development is continued during the ``freeze'' period, -since a new In summary, there is always a -For instance, an experimental encrypted filesystem should probably go +For instance, an experimental encrypted file system should probably go into experimental. A new, beta, version of some software which uses completely different configuration might go into experimental at the maintainer's discretion. New software which isn't likely to damage @@ -515,12 +604,12 @@ your system can go into Release code names

Every released Debian distribution has a Since the Debian has an open development model (i.e., everyone can participate and follow the development) even the ``development @@ -556,8 +645,8 @@ If you want to create a new package for the Debian distribution, you should first check the page. Checking -the WNPP ensures that no-one is already working on packaging that -software, and that effort is not duplicated. Assuming no-one else is +the WNPP ensures that no one is already working on packaging that +software, and that effort is not duplicated. Assuming no one else is already working on your prospective package, you must then send a short email to -I think the announcements gives us a better feel of what is going on, -and what is new, in the project. +The announcements give maintainers and other interested parties a +better feel of what is going on, and what is new, in the project. + We should not dismiss anybody who installs from unstable and helps us @@ -598,10 +688,6 @@ debug our packages as "fools, fools, you installed from unstable; you deserve what you get"--we derive a certain benefit from the alpha testers. - -If we appreciate alpha testers, than any name changes have to be -backwards compatible with the people who already installed the old -package (conflict and replace old package name at a minimum). @@ -650,7 +736,6 @@ to The first time a version is uploaded which corresponds to a particular upstream version the original source tar file should be uploaded and @@ -659,7 +744,7 @@ file should be used to build the new diffs and By default - install the package and make sure the software - works - - upgrade the package from an older version to your - new version - - downgrade the package to the previous version - (this tests the remove the package - - run lintian -v - package-NN.changes. This will check the - source package as well as the binary package. If you - don't understand the output that +Install the package and make sure the software works, or upgrade the +package from an older version to your new version if a Debian package +for it already exists. + + +Run lintian -v package-NN.changes. This will +check the source package as well as the binary package. If you don't +understand the output that +Normally, a package should +For more information on . + +Downgrade the package to the previous version (if one exists) -- this +tests the +Remove the package, then reinstall it. @@ -709,10 +798,19 @@ To upload a package, you need a personal account on have this account. You can use either /home/Debian/ftp/private/project/Incoming. (You -cannot upload to Incoming on master using anonymous FTP--you must use -your user-name and password.) +cannot upload to Incoming on master using anonymous FTP -- you must use +your username and password.) +

+ -You may also find the Debian package To upload a package to the . Note, that +id="ftp://non-us.debian.org/pub/debian-non-US/Incoming">. Note, that the .changes file must have a valid PGP signature from one of -the keys of the developers keyring. +the keys of the developers key-ring. Announcing package uploads @@ -779,15 +877,20 @@ before the start of the +

If a package is released with -If you use dupload, it is clever enough to determine for itself where -the announcement should go, and will automatically mail the -announcement. +On occasion, it is necessary to upload a package to both the +The . Notification that a new package has been installed

@@ -856,7 +959,7 @@ the fixed bugs explaining that they have been fixed. Using set the severity of the bugs fixed in the NMU to "fixed". This ensures that everyone knows that the bug was fixed in an NMU; however the bug is left open until the changes in the NMU are incorporated -"officially" into the package by the offical package maintainer. +"officially" into the package by the official package maintainer.

The normal maintainer should do at least one of the following: @@ -882,12 +985,12 @@ sent to list. This list is also available at in the Work-Needing and Prospective Packages document (WNPP), -and at . If you wish -to take over maintenance of any of the packages listed in the WNPP, or -if you can no longer maintain a packages you have, or you simply want -to know if any one is working on a new package, send a message to -. +If you wish to take over maintenance of any of the packages listed in +the WNPP, or if you can no longer maintain a packages you have, or you +simply want to know if any one is working on a new package, send a +message to If you take over an old package, you probably want to be listed as the package's official maintainer in the bug system. This will happen @@ -905,10 +1008,10 @@ cases. Moving packages

-Sometimes a package will change either it's section or it's -subsection. For instance, a package from the `non-free' section might -be GPL'd in a later version; in this case you should consider moving -it to `main' or `contrib' (see the for guidelines).

@@ -919,15 +1022,15 @@ name="Debian Packaging Manual"> for details). Carefully examine the installation log sent to you when the package is installed into the archive. If for some reason the old location of the package remains, file a bug against -Removing packages

If for some reason you want to completely remove a package (say, if it -is an old compatability library which is not longer required), you -need to file a bug against @@ -944,7 +1047,7 @@ 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 -against , or, if you have -installed the /usr/doc/debian/bug-*.

Often as a package maintainer, you find bugs in other packages or else @@ -1002,12 +1105,13 @@ number. Lintian reports

-You should periodically get the new . -That page, which is updated automatically, contains . +That report, which is updated automatically, contains Reporting lots of bugs at once @@ -1015,80 +1119,79 @@ reports against the latest version of the package (usually from If you report more then 10 bugs on the same topic at once, it is recommended that you send a message to -Note, that when sending lots of bugs on the same subject, you should +Note that when sending lots of bugs on the same subject, you should send the bug report to Whirlwind Tour of Debian Maintainer Tools + Overview of Debian Maintainer Tools

This section contains a rough overview of the tools available to maintainers. These tools are meant to help convenience developers and free their time for critical tasks.

Some people prefer to use high-level package maintenance tools and -some do not. Debian is officially agnostic on this issue, other than -making the attempt to accomodate the reasonable wishes of developers. -Therefore, this section is not meant to stipulate to anyone which -tools they should use or how they should go about with their duties of -maintainership. Nor is it meant to endorse any particular tool to the -exclusion of a competing tool. +some do not. Debian is officially agnostic on this issue; any tool +which gets the job done is fine. Therefore, this section is not meant +to stipulate to anyone which tools they should use or how they should +go about with their duties of maintainership. Nor is it meant to +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. - dpkg-dev + -dpkg-dev contains the tools (including + - lintian + -Lintian dissects Debian packages and reports bugs and +lintian has already been discussed in and . - debhelper + -debhelper is a collection of programs that can be used in +debian/rules to automate common tasks related to building binary Debian packages. Programs are included to install various files into your package, compress files, fix file permissions, integrate your package with the Debian menu system.

-Unlike debmake, debhelper is broken into +Unlike debmake. + - debmake + -debmake, a pre-cursor to debhelper, is a +debian/rules assistant. It includes two main programs: deb-make, which can be used to help a maintainer convert a regular (non-Debian) source archive into a Debian source package; and debstd, which incorporates in one big shot the same sort of automated functions that one finds in -debhelper. + - cvs-buildpackage + -cvs-buildpackage provides the capability to inject or + - dupload + -dupload is a package and a script to automagically upload +