chiark / gitweb /
Use dblatex instead of fop, as long fop is in contrib.
[developers-reference.git] / resources.dbk
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3     "" [
4   <!ENTITY % commondata SYSTEM "common.ent" > %commondata;
5 ]>
6 <chapter id="resources">
7 <title>Resources for Debian Developers</title>
8 <para>
9 In this chapter you will find a very brief road map of the Debian mailing
10 lists, the Debian machines which may be available to you as a developer, and
11 all the other resources that are available to help you in your maintainer work.
12 </para>
13 <section id="mailing-lists">
14 <title>Mailing lists</title>
15 <para>
16 Much of the conversation between Debian developers (and users) is managed
17 through a wide array of mailing lists we host at <literal><ulink
18 url="http://&lists-host;/">&lists-host;</ulink></literal>.
19 To find out more on how to subscribe or unsubscribe, how to post and how not to
20 post, where to find old posts and how to search them, how to contact the list
21 maintainers and see various other information about the mailing lists, please
22 read <ulink url="&url-debian-lists;"></ulink>.  This section
23 will only cover aspects of mailing lists that are of particular interest to
24 developers.
25 </para>
26 <section id="mailing-lists-rules">
27 <title>Basic rules for use</title>
28 <para>
29 When replying to messages on the mailing list, please do not send a carbon copy
30 (<literal>CC</literal>) to the original poster unless they explicitly request
31 to be copied.  Anyone who posts to a mailing list should read it to see the
32 responses.
33 </para>
34 <para>
35 Cross-posting (sending the same message to multiple lists) is discouraged.  As
36 ever on the net, please trim down the quoting of articles you're replying to.
37 In general, please adhere to the usual conventions for posting messages.
38 </para>
39 <para>
40 Please read the <ulink
41 url="&url-debian-lists;#codeofconduct">code of conduct</ulink>
42 for more information.
43 </para>
44 </section>
46 <section id="core-devel-mailing-lists">
47 <title>Core development mailing lists</title>
48 <para>
49 The core Debian mailing lists that developers should use are:
50 </para>
51 <itemizedlist>
52 <listitem>
53 <para>
54 &email-debian-devel-announce;, used to announce important
55 things to developers.  All developers are expected to be subscribed to this
56 list.
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 &email-debian-devel;, used to discuss various development
62 related technical issues.
63 </para>
64 </listitem>
65 <listitem>
66 <para>
67 &email-debian-policy;, where the Debian Policy is discussed
68 and voted on.
69 </para>
70 </listitem>
71 <listitem>
72 <para>
73 &email-debian-project;, used to discuss various non-technical
74 issues related to the project.
75 </para>
76 </listitem>
77 </itemizedlist>
78 <para>
79 There are other mailing lists available for a variety of special topics; see
80 <ulink url="http://&lists-host;/"></ulink> for a list.
81 </para>
82 </section>
84 <section id="mailing-lists-special">
85 <title>Special lists</title>
86 <para>
87 &email-debian-private; is a special mailing list for private
88 discussions amongst Debian developers.  It is meant to be used for posts which
89 for whatever reason should not be published publicly.  As such, it is a low
90 volume list, and users are urged not to use
91 &email-debian-private; unless it is really necessary.
92 Moreover, do <emphasis>not</emphasis> forward email from that list to anyone.
93 Archives of this list are not available on the web for obvious reasons, but you
94 can see them using your shell account on <literal>&lists-host;</literal>
95 and looking in the <filename>&file-debian-private-archive;</filename>
96 directory.
97 </para>
98 <para>
99 &email-debian-email; is a special mailing list used as a
100 grab-bag for Debian related correspondence such as contacting upstream authors
101 about licenses, bugs, etc.  or discussing the project with others where it
102 might be useful to have the discussion archived somewhere.
103 </para>
104 </section>
106 <section id="mailing-lists-new">
107 <title>Requesting new development-related lists</title>
108 <para>
109 Before requesting a mailing list that relates to the development of a package
110 (or a small group of related packages), please consider if using an alias (via
111 a .forward-aliasname file on, which translates into a
112 reasonably nice <replaceable></replaceable> address) or
113 a self-managed mailing list on <link linkend="alioth">Alioth</link> is
114 more appropriate.
115 </para>
116 <para>
117 If you decide that a regular mailing list on &lists-host; is really what
118 you want, go ahead and fill in a request, following <ulink
119 url="&url-debian-lists-new;">the HOWTO</ulink>.
120 </para>
121 </section>
123 </section>
125 <section id="irc-channels">
126 <title>IRC channels</title>
127 <para>
128 Several IRC channels are dedicated to Debian's development.  They are mainly
129 hosted on the <ulink url="&url-oftc;">Open and free technology
130 community (OFTC)</ulink> network.  The <literal></literal> DNS
131 entry is an alias to <literal></literal>.
132 </para>
133 <para>
134 The main channel for Debian in general is <emphasis>#debian</emphasis>.  This
135 is a large, general-purpose channel where users can find recent news in the
136 topic and served by bots.  <emphasis>#debian</emphasis> is for English
137 speakers; there are also <emphasis></emphasis>,
138 <emphasis>#debian-fr</emphasis>, <emphasis>#debian-br</emphasis> and other
139 similarly named channels for speakers of other languages.
140 </para>
141 <para>
142 The main channel for Debian development is <emphasis>#debian-devel</emphasis>.
143 It is a very active channel since usually over 150 people are always logged in.
144 It's a channel for people who work on Debian, it's not a support channel
145 (there's <emphasis>#debian</emphasis> for that).  It is however open to anyone
146 who wants to lurk (and learn).  Its topic is commonly full of interesting
147 information for developers.
148 </para>
149 <para>
150 Since <emphasis>#debian-devel</emphasis> is an open channel, you should not
151 speak there of issues that are discussed in
152 &email-debian-private;.  There's another channel for this
153 purpose, it's called <emphasis>#debian-private</emphasis> and it's protected by
154 a key.  This key is available in the archives of debian-private in
155 <filename>;</filename>,
156 just <command>zgrep</command> for <emphasis>#debian-private</emphasis> in all
157 the files.
158 </para>
159 <para>
160 There are other additional channels dedicated to specific subjects.
161 <emphasis>#debian-bugs</emphasis> is used for coordinating bug squashing
162 parties.  <emphasis>#debian-boot</emphasis> is used to coordinate the work on
163 the debian-installer.  <emphasis>#debian-doc</emphasis> is occasionally used to
164 talk about documentation, like the document you are reading.  Other channels
165 are dedicated to an architecture or a set of packages:
166 <emphasis>#debian-bsd</emphasis>, <emphasis>#debian-kde</emphasis>,
167 <emphasis>#debian-jr</emphasis>, <emphasis>#debian-edu</emphasis>,
168 <emphasis>#debian-sf</emphasis> (SourceForge package),
169 <emphasis>#debian-oo</emphasis> (OpenOffice package) ...
170 </para>
171 <para>
172 Some non-English developers' channels exist as well, for example
173 <emphasis>#debian-devel-fr</emphasis> for French speaking people interested in
174 Debian's development.
175 </para>
176 <para>
177 Channels dedicated to Debian also exist on other IRC networks, notably on the
178 <ulink url="&url-openprojects;">freenode</ulink> IRC network,
179 which was pointed at by the <literal></literal> alias until 4th
180 June 2006.
181 </para>
182 <para>
183 To get a cloak on freenode, you send Jörg Jaspert &lt;; a
184 signed mail where you tell what your nick is.  Put cloak somewhere in the
185 Subject: header.  The nick should be registered: <ulink
186 url="">Nick Setup Page</ulink>.  The
187 mail needs to be signed by a key in the Debian keyring.  Please see <ulink
188 url="">Freenodes
189 documentation</ulink> for more information about cloaks.
190 </para>
191 </section>
193 <section id="doc-rsrcs">
194 <title>Documentation</title>
195 <para>
196 This document contains a lot of information which is useful to Debian
197 developers, but it cannot contain everything.  Most of the other interesting
198 documents are linked from <ulink url="&url-devel-docs;">The
199 Developers' Corner</ulink>.  Take the time to browse all the links, you will
200 learn many more things.
201 </para>
202 </section>
204 <section id="server-machines">
205 <title>Debian machines</title>
206 <para>
207 Debian has several computers working as servers, most of which serve critical
208 functions in the Debian project.  Most of the machines are used for porting
209 activities, and they all have a permanent connection to the Internet.
210 </para>
211 <para>
212 Most of the machines are available for individual developers to use, as long as
213 the developers follow the rules set forth in the <ulink
214 url="&url-dmup;">Debian Machine Usage Policies</ulink>.
215 </para>
216 <para>
217 Generally speaking, you can use these machines for Debian-related purposes as
218 you see fit.  Please be kind to system administrators, and do not use up tons
219 and tons of disk space, network bandwidth, or CPU without first getting the
220 approval of the system administrators.  Usually these machines are run by
221 volunteers.
222 </para>
223 <para>
224 Please take care to protect your Debian passwords and SSH keys installed on
225 Debian machines.  Avoid login or upload methods which send passwords over the
226 Internet in the clear, such as telnet, FTP, POP etc.
227 </para>
228 <para>
229 Please do not put any material that doesn't relate to Debian on the Debian
230 servers, unless you have prior permission.
231 </para>
232 <para>
233 The current list of Debian machines is available at <ulink
234 url="&url-devel-machines;"></ulink>.  That web page contains
235 machine names, contact information, information about who can log in, SSH keys
236 etc.
237 </para>
238 <para>
239 If you have a problem with the operation of a Debian server, and you think that
240 the system operators need to be notified of this problem, the Debian system
241 administrator team is reachable at
242 <email>debian-admin@&lists-host;</email>.
243 </para>
244 <para>
245 If you have a problem with a certain service, not related to the system
246 administration (such as packages to be removed from the archive, suggestions
247 for the web site, etc.), generally you'll report a bug against a
248 ``pseudo-package''.  See <xref linkend="submit-bug"/> for information on how to
249 submit bugs.
250 </para>
251 <para>
252 Some of the core servers are restricted, but the information from there is
253 mirrored to another server.
254 </para>
255 <section id="servers-bugs">
256 <title>The bugs server</title>
257 <para>
258 <literal>&bugs-host;</literal> is the canonical location for
259 the Bug Tracking System (BTS).
260 </para>
261 <para>
262 It is restricted; a mirror is available on <literal>merkel</literal>.
263 </para>
264 <para>
265 If you plan on doing some statistical analysis or processing of Debian bugs,
266 this would be the place to do it.  Please describe your plans on
267 &email-debian-devel; before implementing anything, however, to
268 reduce unnecessary duplication of effort or wasted processing time.
269 </para>
270 </section>
272 <section id="servers-ftp-master">
273 <title>The ftp-master server</title>
274 <para>
275 The <literal>&ftp-master-host;</literal> server holds the canonical copy of
276 the Debian archive (excluding the non-US packages).  Generally, package uploads
277 go to this server; see <xref linkend="upload"/> .
278 </para>
279 <para>
280 It is restricted; a mirror is available on <literal>merkel</literal>.
281 </para>
282 <para>
283 Problems with the Debian FTP archive generally need to be reported as bugs
284 against the <systemitem role="package">&ftp-debian-org;</systemitem>
285 pseudo-package or an email to &email-ftpmaster;, but also see
286 the procedures in <xref linkend="archive-manip"/> .
287 </para>
288 </section>
290 <section id="servers-non-us">
291 <title>The non-US server</title>
292 <para>
293 The non-US server <literal>&non-us-host;</literal> was discontinued with
294 the release of sarge.  The pseudo-package <systemitem
295 role="package"></systemitem> still exists for now.
296 </para>
297 </section>
299 <section id="servers-www">
300 <title>The www-master server</title>
301 <para>
302 The main web server is <literal></literal>.  It holds the
303 official web pages, the face of Debian for most newbies.
304 </para>
305 <para>
306 If you find a problem with the Debian web server, you should generally submit a
307 bug against the pseudo-package, <systemitem
308 role="package"></systemitem>.  Remember to check whether or not
309 someone else has already reported the problem to the <ulink
310 url="http://&bugs-host;/&www-debian-org;">Bug Tracking System</ulink>.
311 </para>
312 </section>
314 <section id="servers-people">
315 <title>The people web server</title>
316 <para>
317 <literal></literal> is the server used for developers' own web
318 pages about anything related to Debian.
319 </para>
320 <para>
321 If you have some Debian-specific information which you want to serve on the
322 web, you can do this by putting material in the
323 <filename>public_html</filename> directory under your home directory on
324 <literal></literal>.  This will be accessible at the URL
325 <literal><replaceable>your-user-id</replaceable>/</literal>.
326 </para>
327 <para>
328 You should only use this particular location because it will be backed up,
329 whereas on other hosts it won't.
330 </para>
331 <para>
332 Usually the only reason to use a different host is when you need to publish
333 materials subject to the U.S.  export restrictions, in which case you can use
334 one of the other servers located outside the United States.
335 </para>
336 <para>
337 Send mail to &email-debian-devel; if you have any questions.
338 </para>
339 </section>
341 <section id="servers-cvs">
342 <title>The CVS server</title>
343 <!-- TODO: document, also -->
344 <para>
345 Our CVS server is located on <literal></literal>.
346 </para>
347 <para>
348 If you need to use a publicly accessible CVS server, for instance, to help
349 coordinate work on a package between many different developers, you can request
350 a CVS area on the server.
351 </para>
352 <para>
353 Generally, <literal></literal> offers a combination of local CVS
354 access, anonymous client-server read-only access, and full client-server access
355 through <command>ssh</command>.  Also, the CVS area can be accessed read-only
356 via the Web at <ulink url="&url-cvsweb;"></ulink>.
357 </para>
358 <para>
359 To request a CVS area, send a request via email to
360 &email-debian-admin;.  Include the name of the requested CVS
361 area, the Debian account that should own the CVS root area, and why you need
362 it.
363 </para>
364 </section>
366 <section id="dchroot">
367 <title>chroots to different distributions</title>
368 <para>
369 On some machines, there are chroots to different distributions available.  You
370 can use them like this:
371 </para>
372 <screen>
373 vore$ dchroot unstable
374 Executing shell in chroot: /org/
375 </screen>
376 <para>
377 In all chroots, the normal user home directories are available.  You can find
378 out which chroots are available via
379 <literal>&url-devel-machines;</literal>.
380 </para>
381 </section>
383 </section>
385 <section id="devel-db">
386 <title>The Developers Database</title>
387 <para>
388 The Developers Database, at <ulink
389 url="&url-debian-db;"></ulink>, is an LDAP directory for
390 managing Debian developer attributes.  You can use this resource to search the
391 list of Debian developers.  Part of this information is also available through
392 the finger service on Debian servers, try <command>finger
393</command> to see what it reports.
394 </para>
395 <para>
396 Developers can <ulink url="&url-debian-db-login;">log into the
397 database</ulink> to change various information about themselves, such as:
398 </para>
399 <itemizedlist>
400 <listitem>
401 <para>
402 forwarding address for your email
403 </para>
404 </listitem>
405 <listitem>
406 <para>
407 subscription to debian-private
408 </para>
409 </listitem>
410 <listitem>
411 <para>
412 whether you are on vacation
413 </para>
414 </listitem>
415 <listitem>
416 <para>
417 personal information such as your address, country, the latitude and longitude
418 of the place where you live for use in <ulink
419 url="&url-worldmap;">the world map of Debian
420 developers</ulink>, phone and fax numbers, IRC nickname and web page
421 </para>
422 </listitem>
423 <listitem>
424 <para>
425 password and preferred shell on Debian Project machines
426 </para>
427 </listitem>
428 </itemizedlist>
429 <para>
430 Most of the information is not accessible to the public, naturally.  For more
431 information please read the online documentation that you can find at <ulink
432 url="&url-debian-db-doc;"></ulink>.
433 </para>
434 <para>
435 Developers can also submit their SSH keys to be used for authorization on the
436 official Debian machines, and even add new * DNS entries.  Those
437 features are documented at <ulink
438 url="&url-debian-db-mail-gw;"></ulink>.
439 </para>
440 </section>
442 <section id="archive">
443 <title>The Debian archive</title>
444 <para>
445 The &debian-formal; distribution consists of a lot of packages
446 (<filename>.deb</filename>'s, currently around
447 &number-of-pkgs;) and a few additional files (such as
448 documentation and installation disk images).
449 </para>
450 <para>
451 Here is an example directory tree of a complete Debian archive:
452 </para>
453 &sample-dist-dirtree;
454 <para>
455 As you can see, the top-level directory contains two directories,
456 <filename>dists/</filename> and <filename>pool/</filename>.  The latter is a
457 “pool” in which the packages actually are, and which is handled by the
458 archive maintenance database and the accompanying programs.  The former
459 contains the distributions, <emphasis>stable</emphasis>,
460 <emphasis>testing</emphasis> and <emphasis>unstable</emphasis>.  The
461 <filename>Packages</filename> and <filename>Sources</filename> files in the
462 distribution subdirectories can reference files in the
463 <filename>pool/</filename> directory.  The directory tree below each of the
464 distributions is arranged in an identical manner.  What we describe below for
465 <emphasis>stable</emphasis> is equally applicable to the
466 <emphasis>unstable</emphasis> and <emphasis>testing</emphasis> distributions.
467 </para>
468 <para>
469 <filename>dists/stable</filename> contains three directories, namely
470 <filename>main</filename>, <filename>contrib</filename>, and
471 <filename>non-free</filename>.
472 </para>
473 <para>
474 In each of the areas, there is a directory for the source packages
475 (<filename>source</filename>) and a directory for each supported architecture
476 (<filename>binary-i386</filename>, <filename>binary-m68k</filename>, etc.).
477 </para>
478 <para>
479 The <filename>main</filename> area contains additional directories which hold
480 the disk images and some essential pieces of documentation required for
481 installing the Debian distribution on a specific architecture
482 (<filename>disks-i386</filename>, <filename>disks-m68k</filename>, etc.).
483 </para>
484 <section id="archive-sections">
485 <title>Sections</title>
486 <para>
487 The <emphasis>main</emphasis> section of the Debian archive is what makes up
488 the <emphasis role="strong">official &debian-formal; distribution</emphasis>.
489 The <emphasis>main</emphasis> section is official because it fully complies
490 with all our guidelines.  The other two sections do not, to different degrees;
491 as such, they are <emphasis role="strong">not</emphasis> officially part of
492 &debian-formal;.
493 </para>
494 <para>
495 Every package in the main section must fully comply with the <ulink
496 url="&url-dfsg;">Debian Free Software
497 Guidelines</ulink> (DFSG) and with all other policy requirements as described
498 in the <ulink url="&url-debian-policy;">Debian Policy
499 Manual</ulink>.  The DFSG is our definition of “free software.” Check out
500 the Debian Policy Manual for details.
501 </para>
502 <para>
503 Packages in the <emphasis>contrib</emphasis> section have to comply with the
504 DFSG, but may fail other requirements.  For instance, they may depend on
505 non-free packages.
506 </para>
507 <para>
508 Packages which do not conform to the DFSG are placed in the
509 <emphasis>non-free</emphasis> section.  These packages are not considered as
510 part of the Debian distribution, though we support their use, and we provide
511 infrastructure (such as our bug-tracking system and mailing lists) for non-free
512 software packages.
513 </para>
514 <para>
515 The <ulink url="&url-debian-policy;">Debian Policy
516 Manual</ulink> contains a more exact definition of the three sections.  The
517 above discussion is just an introduction.
518 </para>
519 <para>
520 The separation of the three sections at the top-level of the archive is
521 important for all people who want to distribute Debian, either via FTP servers
522 on the Internet or on CD-ROMs: by distributing only the
523 <emphasis>main</emphasis> and <emphasis>contrib</emphasis> sections, one can
524 avoid any legal risks.  Some packages in the <emphasis>non-free</emphasis>
525 section do not allow commercial distribution, for example.
526 </para>
527 <para>
528 On the other hand, a CD-ROM vendor could easily check the individual package
529 licenses of the packages in <emphasis>non-free</emphasis> and include as many
530 on the CD-ROMs as it's allowed to.  (Since this varies greatly from vendor to
531 vendor, this job can't be done by the Debian developers.)
532 </para>
533 <para>
534 Note that the term section is also used to refer to categories which simplify
535 the organization and browsing of available packages, e.g.
536 <emphasis>admin</emphasis>, <emphasis>net</emphasis>,
537 <emphasis>utils</emphasis> etc.  Once upon a time, these sections (subsections,
538 rather) existed in the form of subdirectories within the Debian archive.
539 Nowadays, these exist only in the Section header fields of packages.
540 </para>
541 </section>
543 <section id="s4.6.2">
544 <title>Architectures</title>
545 <para>
546 In the first days, the Linux kernel was only available for Intel i386 (or
547 greater) platforms, and so was Debian.  But as Linux became more and more
548 popular, the kernel was ported to other architectures, too.
549 </para>
550 <para>
551 The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola 680x0 (like
552 Atari, Amiga and Macintoshes), MIPS, and PowerPC.  The Linux 2.2 kernel
553 supports even more architectures, including ARM and UltraSPARC.  Since Linux
554 supports these platforms, Debian decided that it should, too.  Therefore,
555 Debian has ports underway; in fact, we also have ports underway to non-Linux
556 kernels.  Aside from <emphasis>i386</emphasis> (our name for Intel x86), there
557 is <emphasis>m68k</emphasis>, <emphasis>alpha</emphasis>,
558 <emphasis>powerpc</emphasis>, <emphasis>sparc</emphasis>,
559 <emphasis>hurd-i386</emphasis>, <emphasis>arm</emphasis>,
560 <emphasis>ia64</emphasis>, <emphasis>hppa</emphasis>,
561 <emphasis>s390</emphasis>, <emphasis>mips</emphasis>,
562 <emphasis>mipsel</emphasis> and <emphasis>sh</emphasis> as of this writing.
563 </para>
564 <para>
565 &debian-formal; 1.3 is only available as <emphasis>i386</emphasis>.  Debian
566 2.0 shipped for <emphasis>i386</emphasis> and <emphasis>m68k</emphasis>
567 architectures.  Debian 2.1 ships for the <emphasis>i386</emphasis>,
568 <emphasis>m68k</emphasis>, <emphasis>alpha</emphasis>, and
569 <emphasis>sparc</emphasis> architectures.  Debian 2.2 added support for the
570 <emphasis>powerpc</emphasis> and <emphasis>arm</emphasis> architectures.
571 Debian 3.0 added support of five new architectures: <emphasis>ia64</emphasis>,
572 <emphasis>hppa</emphasis>, <emphasis>s390</emphasis>, <emphasis>mips</emphasis>
573 and <emphasis>mipsel</emphasis>.
574 </para>
575 <para>
576 Information for developers and users about the specific ports are available at
577 the <ulink url="&url-debian-ports;">Debian Ports web pages</ulink>.
578 </para>
579 </section>
581 <section id="s4.6.3">
582 <title>Packages</title>
583 <para>
584 There are two types of Debian packages, namely <emphasis>source</emphasis> and
585 <emphasis>binary</emphasis> packages.
586 </para>
587 <para>
588 Source packages consist of either two or three files: a
589 <filename>.dsc</filename> file, and either a <filename>.tar.gz</filename> file
590 or both an <filename>.orig.tar.gz</filename> and a
591 <filename>.diff.gz</filename> file.
592 </para>
593 <para>
594 If a package is developed specially for Debian and is not distributed outside
595 of Debian, there is just one <filename>.tar.gz</filename> file which contains
596 the sources of the program.  If a package is distributed elsewhere too, the
597 <filename>.orig.tar.gz</filename> file stores the so-called <emphasis>upstream
598 source code</emphasis>, that is the source code that's distributed by the
599 <emphasis>upstream maintainer</emphasis> (often the author of the software).
600 In this case, the <filename>.diff.gz</filename> contains the changes made by
601 the Debian maintainer.
602 </para>
603 <para>
604 The <filename>.dsc</filename> file lists all the files in the source package
605 together with checksums (<command>md5sums</command>) and some additional info
606 about the package (maintainer, version, etc.).
607 </para>
608 </section>
610 <section id="s4.6.4">
611 <title>Distributions</title>
612 <para>
613 The directory system described in the previous chapter is itself contained
614 within <emphasis>distribution directories</emphasis>.  Each distribution is
615 actually contained in the <filename>pool</filename> directory in the top-level
616 of the Debian archive itself.
617 </para>
618 <para>
619 To summarize, the Debian archive has a root directory within an FTP server.
620 For instance, at the mirror site, <literal></literal>, the
621 Debian archive itself is contained in <ulink
622 url="">/debian</ulink>, which is a common
623 location (another is <filename>/pub/debian</filename>).
624 </para>
625 <para>
626 A distribution comprises Debian source and binary packages, and the respective
627 <filename>Sources</filename> and <filename>Packages</filename> index files,
628 containing the header information from all those packages.  The former are kept
629 in the <filename>pool/</filename> directory, while the latter are kept in the
630 <filename>dists/</filename> directory of the archive (for backwards
631 compatibility).
632 </para>
633 <section id="sec-dists">
634 <title>Stable, testing, and unstable</title>
635 <para>
636 There are always distributions called <emphasis>stable</emphasis> (residing in
637 <filename>dists/stable</filename>), <emphasis>testing</emphasis> (residing in
638 <filename>dists/testing</filename>), and <emphasis>unstable</emphasis>
639 (residing in <filename>dists/unstable</filename>).  This reflects the
640 development process of the Debian project.
641 </para>
642 <para>
643 Active development is done in the <emphasis>unstable</emphasis> distribution
644 (that's why this distribution is sometimes called the <emphasis>development
645 distribution</emphasis>).  Every Debian developer can update his or her
646 packages in this distribution at any time.  Thus, the contents of this
647 distribution change from day to day.  Since no special effort is made to make
648 sure everything in this distribution is working properly, it is sometimes
649 literally unstable.
650 </para>
651 <para>
652 The <link linkend="testing">testing</link> distribution is generated
653 automatically by taking packages from unstable if they satisfy certain
654 criteria.  Those criteria should ensure a good quality for packages within
655 testing.  The update to testing is launched each day after the new packages
656 have been installed.  See <xref linkend="testing"/> .
657 </para>
658 <para>
659 After a period of development, once the release manager deems fit, the
660 <emphasis>testing</emphasis> distribution is frozen, meaning that the policies
661 which control how packages move from <emphasis>unstable</emphasis> to
662 <emphasis>testing</emphasis> are tightened.  Packages which are too buggy are
663 removed.  No changes are allowed into <emphasis>testing</emphasis> except for
664 bug fixes.  After some time has elapsed, depending on progress, the
665 <emphasis>testing</emphasis> distribution is frozen even further.  Details of
666 the handling of the testing distribution are published by the Release Team on
667 debian-devel-announce.  After the open issues are solved to the satisfaction of
668 the Release Team, the distribution is released.  Releasing means that
669 <emphasis>testing</emphasis> is renamed to <emphasis>stable</emphasis>, and a
670 new copy is created for the new <emphasis>testing</emphasis>, and the previous
671 <emphasis>stable</emphasis> is renamed to <emphasis>oldstable</emphasis> and
672 stays there until it is finally archived.  On archiving, the contents are moved
673 to <literal>&archive-host;</literal>).
674 </para>
675 <para>
676 This development cycle is based on the assumption that the
677 <emphasis>unstable</emphasis> distribution becomes <emphasis>stable</emphasis>
678 after passing a period of being in <emphasis>testing</emphasis>.  Even once a
679 distribution is considered stable, a few bugs inevitably remain — that's why
680 the stable distribution is updated every now and then.  However, these updates
681 are tested very carefully and have to be introduced into the archive
682 individually to reduce the risk of introducing new bugs.  You can find proposed
683 additions to <emphasis>stable</emphasis> in the
684 <filename>proposed-updates</filename> directory.  Those packages in
685 <filename>proposed-updates</filename> that pass muster are periodically moved
686 as a batch into the stable distribution and the revision level of the stable
687 distribution is incremented (e.g., ‘3.0’ becomes ‘3.0r1’, ‘2.2r4’
688 becomes ‘2.2r5’, and so forth).  Please refer to
689 <link linkend="upload-stable">uploads to the <emphasis>stable</emphasis>
690 distribution</link> for details.
691 </para>
692 <para>
693 Note that development under <emphasis>unstable</emphasis> continues during the
694 freeze period, since the <emphasis>unstable</emphasis> distribution remains in
695 place in parallel with <emphasis>testing</emphasis>.
696 </para>
697 </section>
699 <section id="s4.6.4.2">
700 <title>More information about the testing distribution</title>
701 <para>
702 Packages are usually installed into the `testing' distribution after they have
703 undergone some degree of testing in unstable.
704 </para>
705 <para>
706 For more details, please see the <link linkend="testing">information about
707 the testing distribution</link>.
708 </para>
709 </section>
711 <section id="experimental">
712 <title>Experimental</title>
713 <para>
714 The <emphasis>experimental</emphasis> distribution is a special distribution.
715 It is not a full distribution in the same sense as `stable' and `unstable' are.
716 Instead, it is meant to be a temporary staging area for highly experimental
717 software where there's a good chance that the software could break your system,
718 or software that's just too unstable even for the <emphasis>unstable</emphasis>
719 distribution (but there is a reason to package it nevertheless).  Users who
720 download and install packages from <emphasis>experimental</emphasis> are
721 expected to have been duly warned.  In short, all bets are off for the
722 <emphasis>experimental</emphasis> distribution.
723 </para>
724 <para>
725 These are the <citerefentry> <refentrytitle>sources.list</refentrytitle>
726 <manvolnum>5</manvolnum> </citerefentry> lines for
727 <emphasis>experimental</emphasis>:
728 </para>
729 <programlisting>
730 deb http://ftp.<replaceable>xy</replaceable> experimental main
731 deb-src http://ftp.<replaceable>xy</replaceable> experimental main
732 </programlisting>
733 <para>
734 If there is a chance that the software could do grave damage to a system, it is
735 likely to be better to put it into <emphasis>experimental</emphasis>.  For
736 instance, an experimental compressed file system should probably go into
737 <emphasis>experimental</emphasis>.
738 </para>
739 <para>
740 Whenever there is a new upstream version of a package that introduces new
741 features but breaks a lot of old ones, it should either not be uploaded, or be
742 uploaded to <emphasis>experimental</emphasis>.  A new, beta, version of some
743 software which uses a completely different configuration can go into
744 <emphasis>experimental</emphasis>, at the maintainer's discretion.  If you are
745 working on an incompatible or complex upgrade situation, you can also use
746 <emphasis>experimental</emphasis> as a staging area, so that testers can get
747 early access.
748 </para>
749 <para>
750 Some experimental software can still go into <emphasis>unstable</emphasis>,
751 with a few warnings in the description, but that isn't recommended because
752 packages from <emphasis>unstable</emphasis> are expected to propagate to
753 <emphasis>testing</emphasis> and thus to <emphasis>stable</emphasis>.  You
754 should not be afraid to use <emphasis>experimental</emphasis> since it does not
755 cause any pain to the ftpmasters, the experimental packages are automatically
756 removed once you upload the package in <emphasis>unstable</emphasis> with a
757 higher version number.
758 </para>
759 <para>
760 New software which isn't likely to damage your system can go directly into
761 <emphasis>unstable</emphasis>.
762 </para>
763 <para>
764 An alternative to <emphasis>experimental</emphasis> is to use your personal web
765 space on <literal></literal>.
766 </para>
767 <para>
768 When uploading to unstable a package which had bugs fixed in experimental,
769 please consider using the option <literal>-v</literal> to
770 <command>dpkg-buildpackage</command> to finally get them closed.
771 </para>
772 </section>
774 </section>
776 <section id="codenames">
777 <title>Release code names</title>
778 <para>
779 Every released Debian distribution has a <emphasis>code name</emphasis>: Debian
780 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0, `hamm';
781 Debian 2.1, `slink'; Debian 2.2, `potato'; Debian 3.0, `woody'; Debian 3.1,
782 sarge; Debian 4.0, etch.  There is also a ``pseudo-distribution'', called
783 `sid', which is the current `unstable' distribution; since packages are moved
784 from `unstable' to `testing' as they approach stability, `sid' itself is never
785 released.  As well as the usual contents of a Debian distribution, `sid'
786 contains packages for architectures which are not yet officially supported or
787 released by Debian.  These architectures are planned to be integrated into the
788 mainstream distribution at some future date.
789 </para>
790 <para>
791 Since Debian has an open development model (i.e., everyone can participate and
792 follow the development) even the `unstable' and `testing' distributions are
793 distributed to the Internet through the Debian FTP and HTTP server network.
794 Thus, if we had called the directory which contains the release candidate
795 version `testing', then we would have to rename it to `stable' when the version
796 is released, which would cause all FTP mirrors to re-retrieve the whole
797 distribution (which is quite large).
798 </para>
799 <para>
800 On the other hand, if we called the distribution directories
801 <emphasis>Debian-x.y</emphasis> from the beginning, people would think that
802 Debian release <emphasis>x.y</emphasis> is available.  (This happened in the
803 past, where a CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0
804 development version.  That's the reason why the first official Debian release
805 was 1.1, and not 1.0.)
806 </para>
807 <para>
808 Thus, the names of the distribution directories in the archive are determined
809 by their code names and not their release status (e.g., `slink').  These names
810 stay the same during the development period and after the release; symbolic
811 links, which can be changed easily, indicate the currently released stable
812 distribution.  That's why the real distribution directories use the
813 <emphasis>code names</emphasis>, while symbolic links for
814 <emphasis>stable</emphasis>, <emphasis>testing</emphasis>, and
815 <emphasis>unstable</emphasis> point to the appropriate release directories.
816 </para>
817 </section>
819 </section>
821 <section id="mirrors">
822 <title>Debian mirrors</title>
823 <para>
824 The various download archives and the web site have several mirrors available
825 in order to relieve our canonical servers from heavy load.  In fact, some of
826 the canonical servers aren't public — a first tier of mirrors balances the
827 load instead.  That way, users always access the mirrors and get used to using
828 them, which allows Debian to better spread its bandwidth requirements over
829 several servers and networks, and basically makes users avoid hammering on one
830 primary location.  Note that the first tier of mirrors is as up-to-date as it
831 can be since they update when triggered from the internal sites (we call this
832 push mirroring).
833 </para>
834 <para>
835 All the information on Debian mirrors, including a list of the available public
836 FTP/HTTP servers, can be found at <ulink
837 url="&url-debian-mirrors;"></ulink>.  This useful page also
838 includes information and tools which can be helpful if you are interested in
839 setting up your own mirror, either for internal or public access.
840 </para>
841 <para>
842 Note that mirrors are generally run by third-parties who are interested in
843 helping Debian.  As such, developers generally do not have accounts on these
844 machines.
845 </para>
846 </section>
848 <section id="incoming-system">
849 <title>The Incoming system</title>
850 <para>
851 The Incoming system is responsible for collecting updated packages and
852 installing them in the Debian archive.  It consists of a set of directories and
853 scripts that are installed on <literal>&ftp-master-host;</literal>.
854 </para>
855 <para>
856 Packages are uploaded by all the maintainers into a directory called
857 <filename>UploadQueue</filename>.  This directory is scanned every few minutes
858 by a daemon called <command>queued</command>,
859 <filename>*.command</filename>-files are executed, and remaining and correctly
860 signed <filename>*.changes</filename>-files are moved together with their
861 corresponding files to the <filename>unchecked</filename> directory.  This
862 directory is not visible for most Developers, as ftp-master is restricted; it
863 is scanned every 15 minutes by the <command>katie</command> script, which
864 verifies the integrity of the uploaded packages and their cryptographic
865 signatures.  If the package is considered ready to be installed, it is moved
866 into the <filename>accepted</filename> directory.  If this is the first upload
867 of the package (or it has new binary packages), it is moved to the
868 <filename>new</filename> directory, where it waits for approval by the
869 ftpmasters.  If the package contains files to be installed by hand it is moved
870 to the <filename>byhand</filename> directory, where it waits for manual
871 installation by the ftpmasters.  Otherwise, if any error has been detected, the
872 package is refused and is moved to the <filename>reject</filename> directory.
873 </para>
874 <para>
875 Once the package is accepted, the system sends a confirmation mail to the
876 maintainer and closes all the bugs marked as fixed by the upload, and the
877 auto-builders may start recompiling it.  The package is now publicly accessible
878 at <ulink url="&url-incoming;"></ulink> until it is really
879 installed in the Debian archive.  This happens only once a day (and is also
880 called the `dinstall run' for historical reasons); the package is then removed
881 from incoming and installed in the pool along with all the other packages.
882 Once all the other updates (generating new <filename>Packages</filename> and
883 <filename>Sources</filename> index files for example) have been made, a special
884 script is called to ask all the primary mirrors to update themselves.
885 </para>
886 <para>
887 The archive maintenance software will also send the OpenPGP/GnuPG signed
888 <filename>.changes</filename> file that you uploaded to the appropriate mailing
889 lists.  If a package is released with the <literal>Distribution:</literal> set
890 to `stable', the announcement is sent to
891 &email-debian-changes;.  If a package is released with
892 <literal>Distribution:</literal> set to `unstable' or `experimental', the
893 announcement will be posted to &email-debian-devel-changes;
894 instead.
895 </para>
896 <para>
897 Though ftp-master is restricted, a copy of the installation is available to all
898 developers on <literal>&ftp-master-mirror;</literal>.
899 </para>
900 <!-- FIXME: delete it or keep it for historical purposes?
901 <para>
902 All Debian developers have write access to the <filename>unchecked</filename>
903 directory in order to upload their packages; they also have that access
904 to the <filename>reject</filename> directory in order to remove their bad uploads
905 or to move some files back to the <filename>unchecked</filename> directory. But
906 all the other directories are only writable by the ftpmasters, which is
907 why you cannot remove an upload once it has been accepted.
908 </para>
910 <section id="delayed-incoming-broken">
911 <title>Delayed incoming</title>
912 <para>
913 <emphasis>Note:</emphasis> This description here is currently not working, because
914 ftp-master is restricted. Please see <xref linkend="delayed-incoming"/> for
915 the currently working way.
916 </para>
917 <para>
918 The <filename>unchecked</filename> directory has a special <filename>DELAYED</filename>
919 subdirectory. It is itself subdivided in nine directories
920 called <filename>1-day</filename> to <filename>9-day</filename>. Packages which are uploaded to
921 one of those directories will be moved to the real unchecked
922 directory after the corresponding number of days.
923 This is done by a script which is run each day and which moves the
924 packages between the directories. Those which are in "1-day" are
925 installed in <filename>unchecked</filename> while the others are moved to the 
926 adjacent directory (for example, a package in <filename>5-day</filename> will
927 be moved to <filename>4-day</filename>). This feature is particularly useful
928 for people who are doing non-maintainer uploads. Instead of
929 waiting before uploading a NMU, it is uploaded as soon as it is
930 ready, but to one of those <filename>DELAYED/<varname>x</varname>-day</filename> directories.
931 That leaves the corresponding number of days for the maintainer
932 to react and upload another fix themselves if they are not
933 completely satisfied with the NMU. Alternatively they can remove
934 the NMU.
935 </para>
936 <para>
937 The use of that delayed feature can be simplified with a bit
938 of integration with your upload tool.  For instance, if you use 
939 <command>dupload</command> (see <xref linkend="dupload"/>), you can add this
940 snippet to your configuration file:
941 <programlisting>
942 $delay = ($ENV{DELAY} || 7);
943 $cfg{'delayed'} = {
944          fqdn => "&ftp-master-host;",
945          login => "yourdebianlogin",
946          incoming => "/org/&ftp-debian-org;/incoming/DELAYED/$delay-day/",
947          dinstall_runs => 1,
948          method => "scpb"
949 };
950 </programlisting>
951 Once you've made that change, <command>dupload</command> can be used to
952 easily upload a package in one of the delayed directories:
953 <literal>DELAY=5 dupload -X-to delayed &lt;changes-file&gt;</literal>
954 </para>
955 </section>
956 -->
957 </section>
959 <section id="pkg-info">
960 <title>Package information</title>
961 <section id="pkg-info-web">
962 <title>On the web</title>
963 <para>
964 Each package has several dedicated web pages.
965 <literal>http://&packages-host;/<replaceable>package-name</replaceable></literal>
966 displays each version of the package available in the various distributions.
967 Each version links to a page which provides information, including the package
968 description, the dependencies, and package download links.
969 </para>
970 <para>
971 The bug tracking system tracks bugs for each package.  You can view the bugs of
972 a given package at the URL
973 <literal>http://&bugs-host;/<replaceable>package-name</replaceable></literal>.
974 </para>
975 </section>
977 <section id="madison">
978 <title>The <command>madison</command> utility</title>
979 <para>
980 <command>madison</command> is a command-line utility that is available on
981 <literal>&ftp-master-host;</literal>, and on the mirror on
982 <literal>&ftp-master-mirror;</literal>.  It uses a single argument corresponding
983 to a package name.  In result it displays which version of the package is
984 available for each architecture and distribution combination.  An example will
985 explain it better.
986 </para>
987 <screen>
988 $ madison libdbd-mysql-perl
989 libdbd-mysql-perl |   1.2202-4 |        stable | source, alpha, arm, i386, m68k, powerpc, sparc
990 libdbd-mysql-perl |   1.2216-2 |       testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
991 libdbd-mysql-perl | 1.2216-2.0.1 |       testing | alpha
992 libdbd-mysql-perl |   1.2219-1 |      unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
993 </screen>
994 <para>
995 In this example, you can see that the version in <emphasis>unstable</emphasis>
996 differs from the version in <emphasis>testing</emphasis> and that there has
997 been a binary-only NMU of the package for the alpha architecture.  Each version
998 of the package has been recompiled on most of the architectures.
999 </para>
1000 </section>
1002 </section>
1004 <section id="pkg-tracking-system">
1005 <title>The Package Tracking System</title>
1006 <para>
1007 The Package Tracking System (PTS) is an email-based tool to track the activity
1008 of a source package.  This really means that you can get the same emails that
1009 the package maintainer gets, simply by subscribing to the package in the PTS.
1010 </para>
1011 <para>
1012 Each email sent through the PTS is classified under one of the keywords listed
1013 below.  This will let you select the mails that you want to receive.
1014 </para>
1015 <para>
1016 By default you will get:
1017 </para>
1018 <variablelist>
1019 <varlistentry>
1020 <term><literal>bts</literal></term>
1021 <listitem>
1022 <para>
1023 All the bug reports and following discussions.
1024 </para>
1025 </listitem>
1026 </varlistentry>
1027 <varlistentry>
1028 <term><literal>bts-control</literal></term>
1029 <listitem>
1030 <para>
1031 The email notifications from <email>control@&bugs-host;</email> about bug
1032 report status changes.
1033 </para>
1034 </listitem>
1035 </varlistentry>
1036 <varlistentry>
1037 <term><literal>upload-source</literal></term>
1038 <listitem>
1039 <para>
1040 The email notification from <command>katie</command> when an uploaded source
1041 package is accepted.
1042 </para>
1043 </listitem>
1044 </varlistentry>
1045 <varlistentry>
1046 <term><literal>katie-other</literal></term>
1047 <listitem>
1048 <para>
1049 Other warning and error emails from <command>katie</command> (such as an
1050 override disparity for the section and/or the priority field).
1051 </para>
1052 </listitem>
1053 </varlistentry>
1054 <varlistentry>
1055 <term><literal>default</literal></term>
1056 <listitem>
1057 <para>
1058 Any non-automatic email sent to the PTS by people who wanted to contact the
1059 subscribers of the package.  This can be done by sending mail to
1060 <literal><replaceable>sourcepackage</replaceable>@&pts-host;</literal>.
1061 In order to prevent spam, all messages sent to these addresses must contain the
1062 <literal>X-PTS-Approved</literal> header with a non-empty value.
1063 </para>
1064 </listitem>
1065 </varlistentry>
1066 <varlistentry>
1067 <term><literal>summary</literal></term>
1068 <listitem>
1069 <para>
1070 Regular summary emails about the package's status.  Currently, only progression
1071 in <emphasis>testing</emphasis> is sent.
1072 </para>
1073 </listitem>
1074 </varlistentry>
1075 </variablelist>
1076 <para>
1077 You can also decide to receive additional information:
1078 </para>
1079 <variablelist>
1080 <varlistentry>
1081 <term><literal>upload-binary</literal></term>
1082 <listitem>
1083 <para>
1084 The email notification from <command>katie</command> when an uploaded binary
1085 package is accepted.  In other words, whenever a build daemon or a porter
1086 uploads your package for another architecture, you can get an email to track
1087 how your package gets recompiled for all architectures.
1088 </para>
1089 </listitem>
1090 </varlistentry>
1091 <varlistentry>
1092 <term><literal>cvs</literal></term>
1093 <listitem>
1094 <para>
1095 CVS commit notifications, if the package has a CVS repository and the
1096 maintainer has set up forwarding commit notifications to the PTS.
1097 </para>
1098 </listitem>
1099 </varlistentry>
1100 <varlistentry>
1101 <term><literal>ddtp</literal></term>
1102 <listitem>
1103 <para>
1104 Translations of descriptions or debconf templates submitted to the Debian
1105 Description Translation Project.
1106 </para>
1107 </listitem>
1108 </varlistentry>
1109 <varlistentry>
1110 <term><literal>derivatives</literal></term>
1111 <listitem>
1112 <para>
1113 Information about changes made to the package in derivative distributions (for
1114 example Ubuntu).
1115 </para>
1116 </listitem>
1117 </varlistentry>
1118 </variablelist>
1119 <section id="pts-commands">
1120 <title>The PTS email interface</title>
1121 <para>
1122 You can control your subscription(s) to the PTS by sending various commands to
1123 <email></email>.
1124 </para>
1125 <variablelist>
1126 <varlistentry>
1127 <term><literal>subscribe &lt;sourcepackage&gt; [&lt;email&gt;]</literal></term>
1128 <listitem>
1129 <para>
1130 Subscribes <replaceable>email</replaceable> to communications related to the
1131 source package <replaceable>sourcepackage</replaceable>.  Sender address is
1132 used if the second argument is not present.  If
1133 <replaceable>sourcepackage</replaceable> is not a valid source package, you'll
1134 get a warning.  However if it's a valid binary package, the PTS will subscribe
1135 you to the corresponding source package.
1136 </para>
1137 </listitem>
1138 </varlistentry>
1139 <varlistentry>
1140 <term><literal>unsubscribe &lt;sourcepackage&gt; [&lt;email&gt;]</literal></term>
1141 <listitem>
1142 <para>
1143 Removes a previous subscription to the source package
1144 <replaceable>sourcepackage</replaceable> using the specified email address or
1145 the sender address if the second argument is left out.
1146 </para>
1147 </listitem>
1148 </varlistentry>
1149 <varlistentry>
1150 <term><literal>unsubscribeall [&lt;email&gt;]</literal></term>
1151 <listitem>
1152 <para>
1153 Removes all subscriptions of the specified email address or the sender address
1154 if the second argument is left out.
1155 </para>
1156 </listitem>
1157 </varlistentry>
1158 <varlistentry>
1159 <term><literal>which [&lt;email&gt;]</literal></term>
1160 <listitem>
1161 <para>
1162 Lists all subscriptions for the sender or the email address optionally
1163 specified.
1164 </para>
1165 </listitem>
1166 </varlistentry>
1167 <varlistentry>
1168 <term><literal>keyword [&lt;email&gt;]</literal></term>
1169 <listitem>
1170 <para>
1171 Tells you the keywords that you are accepting.  For an explanation of keywords,
1172 <link linkend="pkg-tracking-system">see above</link>.  Here's a quick
1173 summary:
1174 </para>
1175 <itemizedlist>
1176 <listitem>
1177 <para>
1178 <literal>bts</literal>: mails coming from the Debian Bug Tracking System
1179 </para>
1180 </listitem>
1181 <listitem>
1182 <para>
1183 <literal>bts-control</literal>: reply to mails sent to
1184 &email-bts-control;
1185 </para>
1186 </listitem>
1187 <listitem>
1188 <para>
1189 <literal>summary</literal>: automatic summary mails about the state of a
1190 package
1191 </para>
1192 </listitem>
1193 <listitem>
1194 <para>
1195 <literal>cvs</literal>: notification of CVS commits
1196 </para>
1197 </listitem>
1198 <listitem>
1199 <para>
1200 <literal>ddtp</literal>: translations of descriptions and debconf templates
1201 </para>
1202 </listitem>
1203 <listitem>
1204 <para>
1205 <literal>derivatives</literal>: changes made on the package by derivative
1206 distributions
1207 </para>
1208 </listitem>
1209 <listitem>
1210 <para>
1211 <literal>upload-source</literal>: announce of a new source upload that has been
1212 accepted
1213 </para>
1214 </listitem>
1215 <listitem>
1216 <para>
1217 <literal>upload-binary</literal>: announce of a new binary-only upload
1218 (porting)
1219 </para>
1220 </listitem>
1221 <listitem>
1222 <para>
1223 <literal>katie-other</literal>: other mails from ftpmasters (override
1224 disparity, etc.)
1225 </para>
1226 </listitem>
1227 <listitem>
1228 <para>
1229 <literal>default</literal>: all the other mails (those which aren't automatic)
1230 </para>
1231 </listitem>
1232 </itemizedlist>
1233 </listitem>
1234 </varlistentry>
1235 <varlistentry>
1236 <term><literal>keyword &lt;sourcepackage&gt; [&lt;email&gt;]</literal></term>
1237 <listitem>
1238 <para>
1239 Same as the previous item but for the given source package, since you may
1240 select a different set of keywords for each source package.
1241 </para>
1242 </listitem>
1243 </varlistentry>
1244 <varlistentry>
1245 <term><literal>keyword [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</literal></term>
1246 <listitem>
1247 <para>
1248 Accept (+) or refuse (-) mails classified under the given keyword(s).  Define
1249 the list (=) of accepted keywords.  This changes the default set of keywords
1250 accepted by a user.
1251 </para>
1252 </listitem>
1253 </varlistentry>
1254 <varlistentry>
1255 <term><literal>keywordall [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</literal></term>
1256 <listitem>
1257 <para>
1258 Accept (+) or refuse (-) mails classified under the given keyword(s).  Define
1259 the list (=) of accepted keywords.  This changes the set of accepted keywords
1260 of all the currently active subscriptions of a user.
1261 </para>
1262 </listitem>
1263 </varlistentry>
1264 <varlistentry>
1265 <term><literal>keyword &lt;sourcepackage&gt; [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</literal></term>
1266 <listitem>
1267 <para>
1268 Same as previous item but overrides the keywords list for the indicated source
1269 package.
1270 </para>
1271 </listitem>
1272 </varlistentry>
1273 <varlistentry>
1274 <term><literal>quit | thanks | --</literal></term>
1275 <listitem>
1276 <para>
1277 Stops processing commands.  All following lines are ignored by the bot.
1278 </para>
1279 </listitem>
1280 </varlistentry>
1281 </variablelist>
1282 <para>
1283 The <command>pts-subscribe</command> command-line utility (from the <systemitem
1284 role="package">devscripts</systemitem> package) can be handy to temporarily
1285 subscribe to some packages, for example after having made an non-maintainer
1286 upload.
1287 </para>
1288 </section>
1290 <section id="pts-mail-filtering">
1291 <title>Filtering PTS mails</title>
1292 <para>
1293 Once you are subscribed to a package, you will get the mails sent to
1294 <literal><replaceable>sourcepackage</replaceable>@&pts-host;</literal>.
1295 Those mails have special headers appended to let you filter them in a special
1296 mailbox (e.g.  with <command>procmail</command>).  The added headers are
1297 <literal>X-Loop</literal>, <literal>X-PTS-Package</literal>,
1298 <literal>X-PTS-Keyword</literal> and <literal>X-Unsubscribe</literal>.
1299 </para>
1300 <para>
1301 Here is an example of added headers for a source upload notification on the
1302 <systemitem role="package">dpkg</systemitem> package:
1303 </para>
1304 <screen>
1305 X-Loop: dpkg@&pts-host;
1306 X-PTS-Package: dpkg
1307 X-PTS-Keyword: upload-source
1308 X-Unsubscribe: echo 'unsubscribe dpkg' | mail
1309 </screen>
1310 </section>
1312 <section id="pts-cvs-commit">
1313 <title>Forwarding CVS commits in the PTS</title>
1314 <para>
1315 If you use a publicly accessible CVS repository for maintaining your Debian
1316 package, you may want to forward the commit notification to the PTS so that the
1317 subscribers (and possible co-maintainers) can closely follow the package's
1318 evolution.
1319 </para>
1320 <para>
1321 Once you set up the CVS repository to generate commit notifications, you just
1322 have to make sure it sends a copy of those mails to
1323 <literal><replaceable>sourcepackage</replaceable>_cvs@&pts-host;</literal>.
1324 Only the people who accept the <emphasis>cvs</emphasis> keyword will receive
1325 these notifications.
1326 </para>
1327 </section>
1329 <section id="pts-web">
1330 <title>The PTS web interface</title>
1331 <para>
1332 The PTS has a web interface at <ulink
1333 url="http://&pts-host;/"></ulink> that puts together a lot of
1334 information about each source package.  It features many useful links (BTS, QA
1335 stats, contact information, DDTP translation status, buildd logs) and gathers
1336 much more information from various places (30 latest changelog entries, testing
1337 status, ...).  It's a very useful tool if you want to know what's going on with
1338 a specific source package.  Furthermore there's a form that allows easy
1339 subscription to the PTS via email.
1340 </para>
1341 <para>
1342 You can jump directly to the web page concerning a specific source package with
1343 a URL like
1344 <literal>http://&pts-host;/<replaceable>sourcepackage</replaceable></literal>.
1345 </para>
1346 <para>
1347 This web interface has been designed like a portal for the development of
1348 packages: you can add custom content on your packages' pages.  You can add
1349 static information (news items that are meant to stay available indefinitely)
1350 and news items in the latest news section.
1351 </para>
1352 <para>
1353 Static news items can be used to indicate:
1354 </para>
1355 <itemizedlist>
1356 <listitem>
1357 <para>
1358 the availability of a project hosted on
1359 <link linkend="alioth">Alioth</link> for co-maintaining the package
1360 </para>
1361 </listitem>
1362 <listitem>
1363 <para>
1364 a link to the upstream web site
1365 </para>
1366 </listitem>
1367 <listitem>
1368 <para>
1369 a link to the upstream bug tracker
1370 </para>
1371 </listitem>
1372 <listitem>
1373 <para>
1374 the existence of an IRC channel dedicated to the software
1375 </para>
1376 </listitem>
1377 <listitem>
1378 <para>
1379 any other available resource that could be useful in the maintenance of the
1380 package
1381 </para>
1382 </listitem>
1383 </itemizedlist>
1384 <para>
1385 Usual news items may be used to announce that:
1386 </para>
1387 <itemizedlist>
1388 <listitem>
1389 <para>
1390 beta packages are available for testing
1391 </para>
1392 </listitem>
1393 <listitem>
1394 <para>
1395 final packages are expected for next week
1396 </para>
1397 </listitem>
1398 <listitem>
1399 <para>
1400 the packaging is about to be redone from scratch
1401 </para>
1402 </listitem>
1403 <listitem>
1404 <para>
1405 backports are available
1406 </para>
1407 </listitem>
1408 <listitem>
1409 <para>
1410 the maintainer is on vacation (if they wish to publish this information)
1411 </para>
1412 </listitem>
1413 <listitem>
1414 <para>
1415 a NMU is being worked on
1416 </para>
1417 </listitem>
1418 <listitem>
1419 <para>
1420 something important will affect the package
1421 </para>
1422 </listitem>
1423 </itemizedlist>
1424 <para>
1425 Both kinds of news are generated in a similar manner: you just have to send an
1426 email either to <email></email> or to
1427 <email></email>.  The mail should indicate which package
1428 is concerned by having the name of the source package in a
1429 <literal>X-PTS-Package</literal> mail header or in a <literal>Package</literal>
1430 pseudo-header (like the BTS reports).  If a URL is available in the
1431 <literal>X-PTS-Url</literal> mail header or in the <literal>Url</literal>
1432 pseudo-header, then the result is a link to that URL instead of a complete news
1433 item.
1434 </para>
1435 <para>
1436 Here are a few examples of valid mails used to generate news items in the PTS.
1437 The first one adds a link to the cvsweb interface of debian-cd in the Static
1438 information section:
1439 </para>
1440 <screen>
1441 From: Raphael Hertzog &lt;;
1442 To:
1443 Subject: Browse debian-cd CVS repository with cvsweb
1445 Package: debian-cd
1446 Url: &url-cvsweb;debian-cd/
1447 </screen>
1448 <para>
1449 The second one is an announcement sent to a mailing list which is also sent to
1450 the PTS so that it is published on the PTS web page of the package.  Note the
1451 use of the BCC field to avoid answers sent to the PTS by mistake.
1452 </para>
1453 <screen>
1454 : Raphael Hertzog &lt;;
1455 To: debian-gtk-gnome@&lists-host;
1456 Bcc:
1457 Subject: Galeon 2.0 backported for woody
1458 X-PTS-Package: galeon
1460 Hello gnomers!
1462 I'm glad to announce that galeon has been backported for woody. You'll find
1463 everything here:
1464 ...
1465 </screen>
1466 <para>
1467 Think twice before adding a news item to the PTS because you won't be able to
1468 remove it later and you won't be able to edit it either.  The only thing that
1469 you can do is send a second news item that will deprecate the information
1470 contained in the previous one.
1471 </para>
1472 </section>
1474 </section>
1476 <section id="ddpo">
1477 <title>Developer's packages overview</title>
1478 <para>
1479 A QA (quality assurance) web portal is available at <ulink
1480 url="&url-ddpo;"></ulink> which displays a table listing all
1481 the packages of a single developer (including those where the party is listed
1482 as a co-maintainer).  The table gives a good summary about the developer's
1483 packages: number of bugs by severity, list of available versions in each
1484 distribution, testing status and much more including links to any other useful
1485 information.
1486 </para>
1487 <para>
1488 It is a good idea to look up your own data regularly so that you don't forget
1489 any open bugs, and so that you don't forget which packages are your
1490 responsibility.
1491 </para>
1492 </section>
1494 <section id="alioth">
1495 <title>Debian *Forge: Alioth</title>
1496 <para>
1497 Alioth is a fairly new Debian service, based on a slightly modified version of
1498 the GForge software (which evolved from SourceForge).  This software offers
1499 developers access to easy-to-use tools such as bug trackers, patch manager,
1500 project/task managers, file hosting services, mailing lists, CVS repositories
1501 etc.  All these tools are managed via a web interface.
1502 </para>
1503 <para>
1504 It is intended to provide facilities to free software projects backed or led by
1505 Debian, facilitate contributions from external developers to projects started
1506 by Debian, and help projects whose goals are the promotion of Debian or its
1507 derivatives.
1508 </para>
1509 <para>
1510 All Debian developers automatically have an account on Alioth.  They can
1511 activate it by using the recover password facility.  External developers can
1512 request guest accounts on Alioth.
1513 </para>
1514 <para>
1515 For more information please visit <ulink
1516 url="&url-alioth;"></ulink>.
1517 </para>
1518 </section>
1520 <section id="developer-misc">
1521 <title>Goodies for Developers</title>
1522 <section id="lwn">
1523 <title>LWN Subscriptions</title>
1524 <para>
1525 Since October of 2002, HP has sponsored a subscription to LWN for all
1526 interested Debian developers.  Details on how to get access to this benefit are
1527 in <ulink
1528 url="http://&lists-host;/debian-devel-announce/2002/10/msg00018.html"></ulink>.
1529 </para>
1530 </section>
1532 </section>
1534 </chapter>