X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=f9c21e0db714bedbcdd5284cc9ddd61b04416f06;hb=60021a3200167fc30b265fcee04aab2595c4a673;hp=98eab132a787492baff5e6ad36e5849dee2a3128;hpb=a02071df6f3f2c7cbf50fbb4a7f74191bbb5cfb8;p=developers-reference.git diff --git a/developers-reference.sgml b/developers-reference.sgml index 98eab13..f9c21e0 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,7 +1,9 @@ - - %versiondata; + + %versiondata; + + ]> -copyright ©1998 Adam Di Carlo, ©1997,1998 -Christian Schwarz + +copyright ©1998, 1999 Adam Di Carlo + +copyright ©1997, 1998 Christian Schwarz

This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the @@ -38,8 +41,8 @@ merchantability or fitness for a particular purpose. See the GNU 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 /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. @@ -63,7 +66,7 @@ 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 an help maintainers with the quality of +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 @@ -74,6 +77,10 @@ name="Debian Packaging Manual">. Nor does this reference detail the standards to which Debian software must comply; that information can be found in the . +

+Furthermore, this document is not an expression of formal +policy. It contains documentation for the Debian system, and +generally agreed-upon best practices. Applying to Become a Maintainer @@ -81,29 +88,31 @@ name="Debian Policy Manual">. 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?

-Firstly, subscribe to debian-devel@lists.debian.org if +you haven't already. Send the word subscribe in the +Subject of an email to +debian-devel-REQUEST@lists.debian.org. In case of problems, contact the list administrator at -. +listmaster@lists.debian.org. More information on +available mailing lists can be found in .

You should subscribe and lurk for a bit before doing any coding, and you should post about your intentions to work on something to avoid duplicated effort.

Another good list to subscribe to is - for -details. The IRC channel debian-mentors@lists.debian.org. See for details. The IRC channel #debian on the +Linux People IRC network (i.e., irc.debian.org) can also be +helpful. - Registering as a Debian developer + Registering as a Debian developer

Before you decide to register with the Debian Project, you will need to read the The process of registering as a developer is a process of verifying your identity and intentions. As the number of people working on -Debian GNU/Linux has grown to over 400 people and our systems are used -in several very important places we have to be careful about being -compromised. Therefore, we need to verify new maintainers before we -can give them accounts on our servers and letting them upload -packages. +Debian GNU/Linux has grown to over &number-of-maintainers; people and +our systems are used in several very important places we have to be +careful about being compromised. Therefore, we need to verify new +maintainers before we can give them accounts on our servers and +letting them upload packages.

Registration requires that the following information be sent to -new-maintainer@debian.org as part of the registration application: Your name. -Your preferred login name on master (seven characters or lessIt is not clear to the author why logins on master cannot be eight characters or greater. If anyone can clarify why, I would appreciate it.), as well as the email address at which you'd prefer to be subscribed to -debian.org address). +debian-private@lists.debian.org (typically this will be +either your primary mail address or your new debian.org +address). A phone number where we can call you. Remember that the new maintainer team usually calls during evening hours to save on long @@ -157,7 +167,7 @@ example, any of the following mechanisms would suffice: A PGP key signed by any well-known signature, such as: -Any current Debian developer you have met in real life. Any formal certification service (such as Verisign, etc.) that verifies your identity. A certification that verifies your email @@ -178,25 +188,29 @@ critical to its security. Many more security failures are due to human error than to software failure or high-powered spy techniques.

Our standard is to use pgp version 2.x. You can use -pgp version 5, if and only if you make an RSA key. Note +that we are also working with the gpg team so that we can +have a free alternative to PGP; however, this may take a little bit of +time.

Your PGP key must be at least 1024 bits long. There is no reason to use a smaller key, and doing so would be much less secure. Your key must be signed with at least your own user ID. This prevents user ID tampering. You can do it by executing pgp -ks -. +your_userid.

-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 key servers. +If your PGP key isn't on public key servers such as +pgp5.ai.mit.edu, please read the documentation available +locally /usr/doc/pgp/keyserv.doc. 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 PGP, have been moved to an ftp site outside of the United States. You can find the current locations of those packages on -ftp.debian.org or +ftp.us.debian.org in the /pub/debian/README.non-US file.

Some countries restrict the use of cryptographic software by their @@ -204,82 +218,118 @@ 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 qua cryptography in any manner. 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.

Once you have all your information ready, and your public key is available on public key servers, send a message to -pgp --kxa in the case of PGP) for the database of keys which is -distributed from new-maintainer@debian.org to register as an offical +Debian developer so that you will be able to upload your packages. +This message must contain all the information discussed above. The +message must also contain your PGP or RSA public key (extracted using +pgp -kxa in the case of PGP) for the database of keys which +is distributed from ftp.debian.org in /pub/debian/doc/debian-keyring.tar.gz, or the -debian-keyring package. Please be sure to sign +your request message with your chosen public key.

Once this information is received and processed, you should be contacted with information about your new Debian maintainer account. If you don't hear anything within 7-14 days, please send a followup -message asking if your original application was received. Do not re-send your original application, that will just confuse +the new-maintainer team. Please be patient, especially near release points; mistakes do occasionally happen, and people do sometimes run out of volunteer time. Debian Mentors

-A mailing list called for -details). +A mailing list called debian-mentors@lists.debian.org +which has been set up for novice maintainers who seek help with +initial packaging and other developer-related issues. Every new +developer is invited to subscribe 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. + + + Maintaining Your Debian Information + + Maintaining Your Public Key +

+Be very careful with your private keys. Do not place them on any +public servers. Back them up. Read the documentation that comes with +your software (either PGP or GNUPG); read the FAQs too, for good +measure. +

+If you add or remove signatures from your public key, or add or remove +user identities, you need to update the key servers and mail your +public key to keyring-maint@debian.org. The same key +extraction routines discussed in apply.

-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. +You can find a more in-depth discussion of Debian key maintenance in +the documentation for the debian-keyring package. + + Retiring Gracefully +

+If you choose to leave the Debian project, you should make sure you do +the following steps: + + +Orphan all your packages, as described in . + +Send an email about how you are leaving the project to +debian-private@lists.debian.org. + +Notify the Debian key ring maintainers that you are leaving by emailing +to keyring-maint@debian.org. + - Mailing Lists and Servers + Mailing Lists, Servers, and Other Machines +

+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. Mailing lists

-The mailing list server is at , lists.debian.org. Mail +debian-foo-REQUEST@lists.debian.org, where +debian-foo is the name of the list, with the word +subscribe in the Subject to subscribe to the list or +unsubscribe to unsubscribe. More detailed instructions on +how to subscribe and unsubscribe to the mailing lists can be found at +, or locally in -/usr/doc/debian/mailing-lists.txt if you have the +/usr/doc/debian/mailing-lists.txt if you have the doc-debian package installed.

When replying to messages on the mailing list, please do not send a -carbon copy (CC) to the original poster unless they explicitly request to be copied. Anyone who posts to a mailing list should read it to see the responses.

In addition, all messages should usually only be sent to one of the -following mailing lists: debian-devel@lists.debian.org, +debian-policy@lists.debian.org, +debian-user@lists.debian.org, +debian-announce@lists.debian.org, or +debian-devel-announce@lists.debian.org. Additional +mailing lists are available for special purposes; see . Cross-posting (sending the same message to multiple lists) is discouraged.

-debian-private@lists.debian.org is a special mailing +lists for private discussions amongst Debian developers. It is meant +to be used for posts which for whatever reason should not be published publically. As such, it is a low volume list, and users are urged not -to use debian-private@lists.debian.org unless it is +really necessary. Moreover, do not forward email from that +list to anyone.

As ever on the net, please trim down the quoting of articles you're replying to. In general, please adhere to the usual conventions for @@ -288,50 +338,68 @@ posting messages. Online archives of mailing lists are available at . + Debian servers +

+Debian servers are well known servers which serve critical functions +in the Debian project. Every developer should know what these servers +are and what they do. +

+If you have a problem with the operation of Debian server, and you +think that the system operators need to be notified of this problem, +please find the contact address for the particular role at . If you have a +non-operating problems (such as packages to be remove, suggestions for +the web site, etc.), generally you'll report a bug against a +``pseudo-package''. See for information on how +to submit bugs. - The master server + The master server

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

-master.debian.org is the canonical location for the Bug +Tracking System (BTS). If you plan on doing some statistical analysis +or processing of Debian bugs, this would be the place to do it. +Please describe your plans on +debian-devel@lists.debian.org before implementing +anything, however, to reduce unnecessary duplication of effort or +wasted processing time.

-All Debian developers have accounts on master.debian.org. Please take care to protect your password to this machine. Try to avoid login or upload methods which send passwords over the Internet in the clear.

-If you find a problem with master.debian.org such as disk full, suspicious activity, or whatever, send an email to -debian-admin@debian.org. +debian-admin@debian.org. Problems with the Debian FTP +archive generally need to be reported as bugs against the +ftp.debian.org pseudo-package or an email to +ftpmaster@debian.org, but also see the procedures in +. - The FTP servers + The WWW servers

- - The WWW servers -

-The main web server, www.debian.org, is also known as +va.debian.org. All developers are given accounts on this machine.

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 public_html directory under your home directory. You can +do this on either va.debian.org or +master.debian.org. Any material you put in those areas are +accessible via the URLs http://www.debian.org/~user-id/ and http://master.debian.org/~user-id/, respectively. -Generally, you'll want to use va, for the +www.debian.org address, although in some cases you may need +to put it on master. Please do not put any material on +Debian servers not relating to Debian, unless you have prior +permission. Send mail to debian-devel@lists.debian.org +if you have any questions.

If you find a problem with the Debian web server, you should generally submit a bug against the pseudo-package, @@ -340,21 +408,27 @@ else has already reported the problem on the . - The CVS server + + The CVS server

-ssh. +cvs.debian.org is also known as va.debian.org, +discussed above. If you need the use of a publically accessible CVS +server, for instance, to help coordinate work on a package between +many different developers, you can request a CVS area on the server. +

+Generally, cvs.debian.org offers a combination of local CVS +access, anonymous client-server read-only access, and full +client-server access through ssh. Also, the CVS area can +be accessed read-only via the Web at .

To request a CVS area, send a request via email to -debian-admin@debian.org. +debian-admin@debian.org. Include the name of the +requested CVS area, what va.debian.org user account should +own the CVSROOT, and why you need it. - Mirrors of Debian 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 @@ -376,17 +450,81 @@ 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.

-Please do not mirror off of master.debian.org. This host +already has too much load. Check the sites above for information, or +email debian-devel@lists.debian.org. + + + Other Debian 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 +be kind to system administrators, and do not use up tons and tons of +disk space, network bandwidth, or CPU without first getting the +approval of the local maintainers. Usually these machines are run by +volunteers. Generally, these machines are for porting activities. +

+Aside from the servers mentioned in , the +following machines are, or may be made, available to you. If an email +address is listed, generally that person is the party to contact about +issues on the machine. Otherwise, the machine is probably managed by +debian-admin@debian.org. + + + faure.debian.org + +An Alpha; if you have an account on master, you probably +already have an account here. + + kubrick.debian.org + +A SPARC; if you have an account on master, you probably +already have an account here. + + pandora.debian.org + +An i386; if you have an account on master, you probably +already have an account here. + + albert.debian.org + +An Alpha; you probably want to use faure instead, but you may +request an account from debian-admin@debian.org. + + powerpc.debian.org + +A PowerPC; also known as tervola.infodrom.north.de. You may +request an account from joey@debian.org or +koptein@debian.org. + + m68k.debian.org + +A Motorola 6800x0 machine; you may request an account from +joey@debian.org or james@nocrew.org. +Runs an autobuilder. + + alpha.debian.nl + +An Alpha; you may request an account from +debian@cistron.nl. + + xia0[123].kachinatech.com + +SPARC and UltraSPARC machines. xia0[12] are used for +automatic compilation; you can request an account on xia03 (an +UltraSPARC) from wdeng@kachinatech.com. + + + + The Debian Archive Overview

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

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

@@ -430,30 +568,30 @@ non-free/source/

As you can see, the top-level directory of the distribution contains -three directories, namely main, contrib, and +non-free. These directories are called sections.

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

-The main section contains additional directories which holds +the disk images and some essential pieces of documentation required +for installing the Debian distribution on a specific architecture +(disks-i386, disks-m68k, etc.).

-The binary and source directories are divided +further into subsections. Sections

The main section is what makes up the official Debian -GNU/Linux distribution. The . The main section is official +because it fully complies with all our guidelines. The other two +sections do not, to different degrees; as such, they are not +officially part of Debian.

Every package in the main section must fully comply with the - -This package is maintained by James Troup. - - + fakeroot

- fakeroot simulates root privileges. This enables +you to build packages without being root (packages usually want to +install files with root ownership). If you have +fakeroot installed, you can say, i.e., +dpkg-buildpackage -rfakeroot as a user. + + + + devscripts

-The devscripts is a package containing a few wrappers +and tools which you may find helpful for maintaining your Debian +packages. Example scripts include debchange, which will +manipulate your debian/changelog file from the +command-line, and build, which is a wrapper around +dpkg-buildpackage. + + + + debget

-We are very excited about this system, since it potentially has so -many uses. Independant development groups can use the system for -different sub-flavors of Debian, which may or may not really be of -general interest (for instance, a flavor of Debian built with gcc -bounds checking). It will also enable Debian to recompile entire -distributions quickly. +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. + + @@ -1649,6 +1975,7 @@ sgml-indent-step:2 sgml-indent-data:nil sgml-parent-document:nil sgml-exposed-tags:nil +sgml-declaration:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: