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