-<!doctype debiandoc system>
-
-<!--
- Debian GNU/Linux Developer's Reference.
- Copyright (C)1997,1998 Christian Schwarz;
- released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- -->
-
+<!doctype debiandoc system [
+<!-- include version information so we don't have to hard code it
+ within the document -->
+<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+]>
+<debiandoc>
<!--
- Topics to be included someday:
+ Topics to be included:
- bugs in upstream versions should be reported upstream!
+ - fill in ftp and www server discussion
-->
-<book>
+ <book>
-<title>Debian Developer's Reference
-<author>Christian Schwarz <email/schwarz@debian.org/
-<author>based on earlier documents by Ian Jackson <email/ijackson@gnu.ai.mit.edu/
-<version>version 2.4.1.2, 14 April 1998
-
-<copyright>Copyright ©1997,1998 Christian Schwarz.
-<p>
+ <title>Debian Developer's Reference
+ <author>Adam P. Harris, current maintainer <email/aph@debian.org/
+ <author>Christian Schwarz <email/schwarz@debian.org/
+ <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+ <version>version &version;, &date;
+ <copyright>
+Copyright ©1998 Adam P. Harris. Copyright ©1997,1998
+Christian Schwarz.
+ <p>
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
-<p>
-
+ <p>
This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose. See the GNU
General Public License for more details.
-<p>
-
+ <p>
A copy of the GNU General Public License is available as
-<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux
-distribution or on the World Wide Web at
-<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it
-by writing to the Free Software Foundation, Inc., 59 Temple Place -
-Suite 330, Boston, MA 02111-1307, USA.
-<p>
+<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux distribution
+or on the World Wide Web at <url
+id="http://www.gnu.org/copyleft/gpl.html">. You can also obtain it by
+writing to the Free Software Foundation, Inc., 59 Temple Place - Suite
+330, Boston, MA 02111-1307, USA.
<toc sect>
- <chapt>Applying to Become a Maintainer<p>
+ <chapt id="scope">Scope of This Document
+ <p>
+The purpose of this document is to provide an overview of the
+processes and resources used by Debian developers.
+ <p>
+The processes discussed within include how to become a maintainer
+(<ref id="new-maintainer">); how to upload new packages (<ref
+id="upload">); how and when to do interim releases of other
+maintainer's packages (<ref id="nmu">); how to move, remove, or orphan
+packages (<ref id="archive-manip">); and how to handle bug reports
+(<ref id="bug-handling">).
+ <p>
+The resources discussed in this reference include the mailing lists
+and servers (<ref id="servers">); a discussion of the structure of the
+Debian archive (<ref id="archive">); explanation of the different
+servers which accept package uploads (<ref id="upload-master">); and a
+discussion of resources which an help maintainers with the quality of
+their packages (<ref id="tools">).
+ <p>
+It should be clear that this reference does not discuss the details of
+the Debian package or how to generate Debian packages; that is
+discussed in the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual">. Nor is this reference intended to
+give details on standards for how Debian software must behave, which
+is documented in the <url
+id="http://www.debian.org/doc/debian-policy/" name="Debian Policy
+Manual">.
+
+
+ <chapt id="new-maintainer">Applying to Become a Maintainer
<sect>Getting started
<p>
-
- So, you've read all the documentation, you understand what
- everything in the <prgn/hello/ example package is for, and
- you're about to Debianise your favourite package. How do
- you actually become a Debian developer so that your work can
- be incorporated into the Project?
- <p>
-
- Firstly, subscribe to <prgn/debian-devel/ if you haven't
- already. Send the word <tt/subscribe/ in the <em/Subject/
- of a mail to <email/debian-devel-REQUEST@lists.debian.org/.
- In case of problems contact the list administrator at
- <email/listmaster@lists.debian.org/.
- <p>
+So, you've read all the documentation, you understand what everything
+in the <prgn/hello/ example package is for, and you're about to
+Debianise your favourite piece of software. How do you actually
+become a Debian developer so that your work can be incorporated into
+the Project?
+ <p>
+Firstly, subscribe to <email/debian-devel@lists.debian.org/ if you
+haven't already. Send the word <tt/subscribe/ in the <em/Subject/ of
+a mail to <email/debian-devel-REQUEST@lists.debian.org/. In case of
+problems contact the list administrator at
+<email/listmaster@lists.debian.org/. More information on available
+mailing lists can be found in <ref id="mailing-lists">.
+ <p>
+You should subscribe and lurk for a bit before doing any coding, and
+you should post about your intentions to work on something to avoid
+duplicated effort.
+ <p>
+Another good list to subscribe to is
+<email/debian-mentors@lists.debian.org/. See <ref id="mentors"> for
+details. The IRC channel <tt/#debian/ on the Linux People IRC network
+(i.e., <tt/irc.debian.org/) can also be helpful.
- You should subscribe and lurk for a bit before doing any
- coding, and you should post about your intentions to work on
- something to avoid duplicated effort.
- <p>
- If you do not have a PGP key yet generate one. You should
- probably read the PGP manual, as it has much important
- information which is critical to its security. Many more
- security failures are due to human error than to software
- failure or high-powered spy techniques.
+ <sect>Registering as a Debian developer
<p>
+Before you decide to work in the Debian Project you have to read the
+<url id="http://www.debian.org/social_contract" name="Debian Social
+Contract">. Registering as a developer means that you agree with and
+pledge to uphold the Debian Social Contract; it is very important that
+maintainers are in accord with the essential ideas behind Debian
+GNU/Linux. Reading the <url
+id="http://www.gnu.org/gnu/manifesto.html" name="GNU Manifesto"> would
+also be a good idea.
+ <p>
+The process of registering as a developer is a process of verifying
+your identity and intentions. As the number of people working on
+Debian GNU/Linux has grown to over 400 people and our systems are used
+in several very important places we have to be careful about being
+compromised. Therefore, we need to verify new maintainers before we
+can give them accounts on our servers and letting them upload
+packages.
+ <p>
+Registration requires that the following information be sent to
+<email/new-maintainer@debian.org/ as part of the registration
+application:
+<list>
+ <item>
+Your name.
+ <item>
+Your preferred login name on <tt/master/ (seven characters or
+less<footnote>Can anyone clarify for me why logins on <tt>master</tt>
+cannot be eight characters?</footnote> ), as well as the email address
+at which you'd prefer to be subscribed to
+<email/debian-private@lists.debian.org/ (typically this will be either
+your primary mail address or your new <tt>debian.org</tt> address).
+ <item>
+A phone number where we can call you.
+ <item>
+A statement of intention, that is, what package(s) you intend to work
+on, which Debian port you will be assisting, or how you intend to
+contribute to Debian.
+ <item>
+A statement that you have read and agree to uphold the <url
+id="http://www.debian.org/social_contract" name="Debian Social
+Contract">.
+ <item>
+Some mechanism by which we can verify your real-life identity. For
+example, any of the following mechanisms would suffice:
+<list>
+ <item>
+A PGP key signed by any well-known signature, such as:
+<list>
+ <item>
+Any current Debian developer you have met <em/in real life/.
+ <item>
+Any formal certification service (such as Verisign, etc.) that
+verifies your identity. A certification that verifies your email
+address, and not you identity, is not sufficient.
+ </list>
+ <item>
+Alternatively, you may identify yourself with a scanned (or physically
+mailed) copy of any formal documents certifying your identity (such as
+a birth certificate, national ID card, U.S. Driver's License, etc.).
+If emailed, please sign the mail with your PGP key.
+ </list>
+ </list>
+If you do not have a PGP key yet, generate one. Every developer needs
+a PGP key in order to sign and verify package uploads. You should read
+the PGP manual, since it has much important information which is
+critical to its security. Many more security failures are due to
+human error than to software failure or high-powered spy techniques.
+ <p>
+Your PGP key must be at least 1024 bits long. There is no reason to
+use a smaller key, and doing so would be much less secure. Your key
+must be signed with at least your own user ID. This prevents user ID
+tampering. You can do it by executing `<tt>pgp -ks
+<var/your_userid/</tt>'.
+ <p>
+If your PGP key isn't on public PGP key servers such as
+<tt>pgp.net</tt>, please read the documentation available locally
+<tt>/usr/doc/pgp/keyserv.doc</tt>. That document contains
+instructions on how to put your key on the public keyservers.
+ <p>
+Due to export restrictions by the United States government some Debian
+packages, including PGP, have been moved to an ftp site outside of the
+United States. You can find the current locations of those packages on
+<ftpsite/ftp.debian.org/ or <ftpsite/ftp.us.debian.org/ in the
+<ftppath>/pub/debian/README.non-US</ftppath> file.
+ <p>
+If you live in a country where use of cryptography even for
+authentication is forbidden then please contact us so we can make
+special arrangements. This does not apply in France, where I believe
+only encryption and not authentication is forbidden.
+ <p>
+Once you have all your information ready, and your public key is
+available on public key servers, send a message to
+<email/new-maintainer@debian.org/ to register as an offical Debian
+developer so that you will be able to upload your packages. This
+message must all the information discussed above. The message must
+also contain your PGP or RSA public key (extracted using <tt>pgp
+-kxa</tt> in the case of PGP; note that <tt/gpg/ integration is
+underway) for the database of keys which is distributed from
+<ftpsite/ftp.debian.org/ in
+<ftppath>/pub/debian/doc/debian-keyring.tar.gz</ftppath>, or the
+<prgn>debian-keyring</prgn> package). Please be sure to sign your
+request message with your chosen PGP or RSA key.
+ <p>
+Once this information is received and processed, you should be
+contacted with information about your new Debian maintainer account.
+If you don't hear anything within 7-14 days, please re-send your
+original message--the new-maintainer volunteers are typically
+overworked, and mistakes do occasionally happen.
- Due to export restrictions by the United States government
- some Debian packages, including PGP, have been moved to an
- ftp site outside of the United States. You can find the
- current locations of those packages on
- <ftpsite/ftp.debian.org/ in the
- <ftppath>/pub/debian/README.non-US</> file.
- <p>
- If you live in a country where use of cryptography even for
- authentication is forbidden then please contact us so we can
- make special arrangements. This does not apply in France,
- where I believe only encryption and not authentication is
- forbidden.
+ <sect id="mentors">Debian Mentors
<p>
-
- <sect>Registering as a Debian developer
+There is a mailing list called <email/debian-mentors@lists.debian.org/
+which has been set up for newbie maintainers who seek help with
+initial packaging and other developer-related issues. Every new
+developer is invited to subscribe to that list (see <ref
+id="mailing-lists"> for details).
<p>
+Those who prefer one-on-one help (e.g., via private emails) should
+also post to that list and an experienced developer will volunteer to
+help.
+
+
+ <chapt id="servers">Mailing Lists and Servers
+
+ <sect id="mailing-lists">Mailing lists
+ <p>
+The mailing list server is at <tt/lists.debian.org/. Mail
+<tt/debian-<var/foo/-REQUEST@lists.debian.org/, where
+<tt/debian-<var/foo// is the name of the list, with the word
+<tt/subscribe/ in the <em/Subject/ to subscribe or <tt/unsubscribe/ to
+unsubscribe. More detailed instructions on how to subscribe and
+unsubscribe to the mailing lists can be found at <url
+id="http://www.debian.org/MailingLists/subscribe">, <url
+id="ftp://ftp.debian.org/debian/doc/mailing-lists.txt"> or locally in
+<tt>/usr/doc/debian/mailing-lists.txt</tt> if you have the
+<prgn>doc-debian</prgn> package installed.
+ <p>
+When replying to messages on the mailing list, please do not send a
+carbon copy (<tt/CC/--this does not mean `courtesy copy') to the
+original poster. Anyone who posts to a mailing list should read it to
+see the responses.
+ <p>
+In addition, all messages should usually only be sent to one of the
+following mailing lists: <email/debian-devel@lists.debian.org/,
+<email/debian-policy@lists.debian.org/,
+<email/debian-user@lists.debian.org/,
+<email/debian-announce@lists.debian.org/, or
+<email/debian-devel-announce@lists.debian.org/. Additional mailing
+lists are available for special purposes; see <url
+id="http://www.debian.org/MailingLists/subscribe">. Cross-posting is
+discouraged.
+ <p>
+<email/debian-private@lists.debian.org/ is a special mailing lists for
+private discussions amongst Debian developers. It is meant to be used
+for posts which for whatever reason should not be published
+publically. As such, it is a low volume list, and users are urged not
+to use <email/debian-private@lists.debian.org/ unless it is really
+necessary. Moreover, do <em/not/ forward email from that list to
+anyone.
+ <p>
+As ever on the net, please trim down the quoting of articles you're
+replying to. In general, please adhere to the usual conventions for
+posting messages.
+ <p>
+Online archives of mailing lists are available at <url
+id="http://www.debian.org/Lists-Archives/">.
+
- Before you decide to work in the Debian Project you have to
- read the ``Debian Social Contract'' (available on
- <tt/www.debian.org/).
- <p>
- After that, you should send a message to
- <email/new-maintainer@debian.org/ to register as an
- 'offical' Debian developer so that you will be able to
- upload your packages.
- <p>
- The message should say what you've done and who you are, and
- should ask for an account on master and to be subscribed to
- debian-private (the developers-only mailing list). It should
- contain your PGP or RSA public key (extracted using `pgp
- -kxa', in the case of PGP) for the database of keys which is
- distributed on the FTP server
- (<tt>doc/debian-keyring.tar.gz</tt>). Please be sure to
- sign your request message with your chosen PGP or RSA
- key. In addition, you have to mention that you've read the
- ``Debian Social Contract'' (see above) and you are expected
- to know where to find the ``Debian Policy Manual'' and the
- ``Debian Packaging Manual.''
- <p>
- Please be sure to include your preferred login name on
- master (seven characters or less), as well as the E-mail
- address at which you'd prefer to be subscribed to
- debian-private (typically this will be either your primary
- mail address or your new debian.org address).
- <p>
- You should also include some mechanism by which we can
- verify your real-life identity. For example, any of the
- following mechanisms would suffice:
-
- <list compact>
- <item>A PGP or RSA key signed by any well-known signature,
- such as any current Debian developer.
- <item>A scanned (or physically mailed) copy of any formal
- documents certifying your identity (such as a birth
- certificate, national ID card, U.S. Driver's License,
- etc.). Please sign the image with your PGP or RSA key.
- </list>
-
- The following mechanisms are discouraged, but are acceptable if
- neither of the first two mechanisms is practical:
- <list compact>
- <item>A pointer to a phone listing at which you could be
- reached (at our expense). This phone listing should
- be verifiable independently through external means
- such as a national directory-listing service or other
- authoritative source.
- <item>Any other mechanism by which you can establish your
- real-life identity with reasonable certainty.
- </list>
-
- We're sorry about the inconvenience of requiring proof of
- identity, but for the moment, such measures are
- unfortunately the only way we can ensure the security and
- reliability of our distribution.
- <p>
-
- Once this information is received and processed, you should
- be contacted with information about your new Debian
- maintainer account. If you don't hear anything within 7-10
- days, please re-send your original message--the
- new-maintainer volunteers are typically overworked, and
- mistakes do occasionally happen.
- <p>
-
- <sect>Debian Mentors
- <p>
-
- There is a mailing list called <tt/debian-mentors/ which has
- been set up for newbie maintainers who seek help with
- initial packaging and other developer-related issues.
- <p>
- Every new developer is invited to subscribe to that list
- (see <ref id="mailing-lists"> for details).
- <p>
- Those who prefer one-on-one help (e.g., via private emails)
- should also post to that list and an experienced developer
- will volunteer to help.
- <p>
-
-
- <chapt>Internet Servers<p>
-
- <sect id="mailing-lists">Mailing lists<p>
-
- The mailing list server is at <tt/lists.debian.org/. Mail
- <tt/debian-<var/foo/-REQUEST@lists.debian.org/, where
- <tt/debian-<var/foo// is the name of the list, with the word
- <tt/subscribe/ in the Subject to subscribe or
- <tt/unsubscribe/ to unsubscribe.
- <p>
- When replying to messages on the mailing list, please do not
- send a carbon copy (<tt/CC/--this does not mean `courtesy
- copy') to the original poster. Anyone who posts to a
- mailing list should read it to see the responses.
- <p>
- In addition, all messages should usually only be sent to one
- of the following mailing lists: <tt/debian-devel/,
- <tt/debian-policy/, <tt/debian-user/, <tt/debian-announce/,
- <tt/debian-devel-announce/.
- <p>
- As ever on the net, please trim down the quoting of articles
- you're replying to. In general, please adhere to the usual
- conventions for posting messages.
- <p>
-
<sect>The master server
<p>
+The master server, <tt/master.debian.org/, holds the cannonical copy
+of the Debian archive (excluding the non-U.S. packages). Generally,
+package uploads go to this server; cf. <ref id="upload">. All Debian
+developers have accounts on this machine.
<sect>The FTP servers
<p>
<sect>The WWW servers
<p>
- <chapt>The Debian Archive<p>
-
+
+ <chapt id="archive">The Debian Archive
+
<sect>Overview
<p>
+The Debian GNU/Linux distribution consists of a lot of Debian packages
+(<tt/.deb/'s, currently more than 1500) and a few additional files
+(documentation, installation disk images, etc.).
+ <p>
+Here is an example directory tree of a complete Debian distribution:
+<example>
+main/
+main/binary-all/
+main/binary-all/admin/
+main/binary-all/base/
+main/binary-all/comm/
+main/binary-all/devel/
+ ...
+main/binary-i386/
+main/binary-m86k/
+ ...
+main/source/
+main/disks-i386/
+main/disks-m68k/
+ ...
+
+contrib/
+contrib/binary-all/
+contrib/binary-i386/
+contrib/binary-m86k/
+ ...
+contrib/source/
+
+non-free/
+non-free/binary-all/
+non-free/binary-i386/
+non-free/binary-m86k/
+ ...
+non-free/source/
+</example>
+ <p>
+As you can see, the top-level directory of the distribution contains
+three directories, namely <em>main</>, <em>contrib</>, and
+<em>non-free</>. These directories are called <em>sections</>.
+ <p>
+In each section, there is a directory with the source packages
+(source), a directory for each supported architecture (binary-i386,
+binary-m86k, etc.), and a directory for architecture independent
+packages (binary-all).
+ <p>
+The <em/main/ section contains additional directories which holds the
+disk images and some essential pieces of documentation required for
+installing the Debian distribution on a specific architecture
+(disks-i386, disks-m68k, etc.).
+ <p>
+The <em/binary/ and <em/source/ directories are divided further into
+<em/subsections/.
+
- The Debian GNU/Linux distribution consists of a lot of
- Debian packages (<tt/.deb/'s, currently more than 1000) and
- a few additional files (documentation, installation disk
- images, etc.).
- <p>
- Here is an example directory tree of a complete Debian
- distribution:
- <example>
- main/
- main/binary-all/
- main/binary-all/admin/
- main/binary-all/base/
- main/binary-all/comm/
- main/binary-all/devel/
- ...
- main/binary-i386/
- main/binary-m86k/
- ...
- main/source/
- main/disks-i386/
- main/disks-m68k/
- ...
-
- contrib/
- contrib/binary-all/
- contrib/binary-i386/
- contrib/binary-m86k/
- ...
- contrib/source/
-
- non-free/
- non-free/binary-all/
- non-free/binary-i386/
- non-free/binary-m86k/
- ...
- non-free/source/
- </example>
- <p>
- As you can see, the top-level directory of the distribution
- contains three directories, namely <em>main</>,
- <em>contrib</>, and <em>non-free</>. These directories are
- called <em>sections</>.
- <p>
- In each section, there is a directory with the source
- packages (source), a directory for each supported
- architecture (binary-i386, binary-m86k, etc.), and a
- directory for architecture independent packages
- (binary-all).
- <p>
- The <em/main/ section contains additional directories which
- holds the disk images and some essential pieces of
- documentation required for installing the Debian
- distribution on a specific architecture (disks-i386,
- disks-m68k, etc.).
- <p>
- The <em/binary/ and <em/source/ directories are divided
- further into <em/sub-sections/.
- <p>
-
<sect>Sections
<p>
+The <em>main</em> section is what makes up the <em>Debian GNU/Linux
+distribution</>. This is because the packages in the other two
+sections do not fully comply with all our guidelines. As such, they
+are not officially part of Debian.
+ <p>
+For example, every package in the main distribution must fully comply
+with the <url id="http://www.debian.org/social_contract#guidelines"
+name="Debian Free Software Guidelines"> (DFSG) and with all other
+policy requirements as described in the <url
+id="http://www.debian.org/doc/debian-policy/" name="Debian Policy
+Manual">. (The DFSG is our definition of ``free software.'' Check out
+the Debian Policy Manual for details.)
+ <p>
+The packages which do not apply to the DFSG are placed in the
+<em/non-free/ section. These packages are not considered as part of
+the Debian distribution, though we support their use, and we provide
+infrastructure (such as our bug-tracking system and mailing lists) for
+non-free software packages.
+ <p>
+Packages in the <em/contrib/ section have to apply to the DFSG, but
+fail other requirements. For instance, they might depend on non-free
+packages.
+ <p>
+(The <url id="http://www.debian.org/doc/debian-policy/" name="Debian
+Policy Manual"> contains a more exact definition of the three
+sections. This is just meant to be an introduction.)
+ <p>
+The separation of the three sections at the top-level of the archive
+is important for all people who want to distribute Debian, either via
+FTP servers on the Internet or on CD-ROMs: by distributing only the
+<em/main/ and <em/contrib/ sections, one can avoid any legal risks.
+Some packages in the <em/non-free/ section do not allow commercial
+distribution, for example.
+ <p>
+On the other hand, a CD-ROM vendor could easily check the individual
+package licenses of the packages in <em/non-free/ and include as many
+on the CD-ROMs as he's allowed. (Since this varies from vendor to
+vendor very much, this job can't be done by the Debian developers.)
- The <em>main section</> is what makes up the <em>Debian
- GNU/Linux distribution</>. This is because the packages in
- the other two sections do not fully comply with all our
- guidelines.
- <p>
- For example, every package in the main distribution must
- fully comply with the <em>Debian Free Software Guidelines</>
- (DFSG) and with all other policy requirements as described
- in the <em>Debian Policy Manual</em>. (The DFSG is our
- definition of ``free software.'' Check out the Debian Policy
- Manual for details.)
- <p>
- The packages which do not apply to the DFSG are placed in
- the <em>non-free</> section. These packages are not
- considered as part of the Debian distribution, though we
- support their use, and we provide infrastructure (such as
- our bug-tracking system and mailing lists) for non-free
- software packages.
- <p>
- Packages in the <em>contrib</> section have to apply to
- the DFSG, but fail other requirements.
- <p>
- (The Debian Policy Manual contains a more exact definition
- of the three sections. This is just meant to be an
- introduction.)
- <p>
- The separation of the three sections at the top-level of
- the archive is important for all people who want to
- distribute Debian, either via FTP servers on the Internet
- or on CD-ROMs: by distributing only the <em/main/ and
- <em/contrib/ sections, one can avoid any legal risks,
- since some packages in the <em/non-free/ section do not
- allow commercial distribution, for example.
- <p>
- On the other hand, a CD-ROM vendor could easily check the
- individual package licenses of the packages in <em/non-free/
- and include as many on the CD-ROMs as he's allowed. (Since
- this varies from vendor to vendor very much, this job can't
- be done by the Debian developers.)
- <p>
<sect>Architectures
<p>
-
- In the first days, the Linux kernel was only available for
- the Intel i386 (or greater) platforms, and so was
- Debian. But when Linux became more and more popular, the
- kernel was ported to other architectures, too.
- <p>
- The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs,
- M68000 machines (like Atari and Amiga), MIPS, and
- PowerPC.
+In the first days, the Linux kernel was only available for the Intel
+i386 (or greater) platforms, and so was Debian. But when Linux became
+more and more popular, the kernel was ported to other architectures,
+too.
<p>
- Debian GNU/Linux 1.3 is only available for Intel
- platforms. One of the goals for Debian 2.0 is to support
- some of the other architectures, too.
+The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, M68000
+machines (like Atari and Amiga), MIPS, and PowerPC.
<p>
+Debian GNU/Linux 1.3 is only available for Intel platforms. Debian
+2.0 supports Intel and m68k architectures. The next version of Debian
+is likely to also support Alpha, PPC, and Sparc architectures, if not
+more.
- <sect>Sub sections
- <p>
- The sections <em/main/, <em/contrib/, and <em/non-free/ are
- split into <em/sub sections/, to simplify the installation
- process and the maintainance of the archive.
- <p>
+ <sect>Subsections
+ <p>
+The sections <em/main/, <em/contrib/, and <em/non-free/ are split into
+<em/subsections/, to simplify the installation process and the
+maintainance of the archive. Subsections are not formally defined,
+excepting perhaps for the "base" subsection. Subsections exist simply
+to simpilfy the organization and browsing of available packages.
+Please check the current Debian distribution to see which sections are
+available.
+
- <sect>Packages
- <p>
- There are two types of Debian packages, namely <em/source/
- and <em/binary/ packages.
+ <sect>Packages
<p>
- Source packages consist of either two or three files: a
- <tt/.dsc/ file, and either one <tt/.tar.gz/ file or a
- <tt/.orig.tar.gz/ and a <tt/.diff.gz/ file.
+There are two types of Debian packages, namely <em/source/ and
+<em/binary/ packages.
<p>
- If a package is developed specially for Debian and is not
- distributed outside of Debian, there is just one
- <tt/.tar.gz/ file which contains the sources of the program.
+Source packages consist of either two or three files: a <tt/.dsc/
+file, and either one <tt/.tar.gz/ file or a <tt/.orig.tar.gz/ and a
+<tt/.diff.gz/ file.
<p>
- If a package is distributed elsewhere too, the
- <tt/.orig.tar.gz/ file stores the so-called <em/upstream
- source code/, that is the source code that's distributed
- from the <em/upstream maintainer/ (author). In this case,
- the <tt/.diff.gz/ contains the changes made by the Debian
- maintainer.
+If a package is developed specially for Debian and is not distributed
+outside of Debian, there is just one <tt/.tar.gz/ file which contains
+the sources of the program.
<p>
- The <tt/.dsc/ lists all components of the source package
- together with checksums (md5sums) and some additional info
- about the package (maintainer, version, etc.).
+If a package is distributed elsewhere too, the <tt/.orig.tar.gz/ file
+stores the so-called <em/upstream source code/, that is the source
+code that's distributed from the <em/upstream maintainer/ (author). In
+this case, the <tt/.diff.gz/ contains the changes made by the Debian
+maintainer.
<p>
+The <tt/.dsc/ lists all components of the source package together with
+checksums (md5sums) and some additional info about the package
+(maintainer, version, etc.).
+
<sect>Distribution directories
<p>
+If you have a look at the Debian FTP server or one of its mirrors,
+you'll discover that there is one additional directory level on top of
+the directory tree, as described in the previous chapter. These
+directories are the <em/distribution directories/. All distributions
+are contained in the <tt/dists/ directory in the top-level of the
+Debian archive (the symlinks from the top-level directory to the
+distributions themselves is for backwards compatability and
+deprecated).
- If you have a look at the Debian FTP server or one of its
- mirrors, you'll discover that there is one additional
- directory level on top of the directory tree, as described
- in the previous chapter. These directories are the
- <em/distribution directories/.
- <p>
- There is always a distribution called <em/stable/ and one
- called <em/unstable/. This reflects the development process
- of the Debian project:
- <p>
- The ``development'' is done in the <em/unstable/
- distribution (that's why this distribution is sometimes
- called <em/development distribution/). Every Debian
- developer can update his/her packages in this distribution
- at any time. Thus, the contents of this distribution changes
- from day to day and since no special effort is done to test
- this distribution it's sometimes ``unstable.''
- <p>
- After about two months of development, the <em/unstable/
- distribution is copied in a new distribution directory,
- called <em/frozen/. After that, no changes are allowed to
- the frozen distribution, except bug fixes. (That's why it's
- called ``frozen.'')
- <p>
- After another month or a little longer, the <em/frozen/
- distribution is renamed to <em/stable/, overriding the old
- <em/stable/ distribution, which is removed at that time.
- <p>
- This development cycle is based on the assumption, that the
- once `unstable' distribution finally becomes `stable' after
- passing one month of testing. Unfortunately, a few bugs
- still remain--that's why the stable distribution is updated
- every few weeks. However, these updates are tested very
- carefully and have to be acknowledged individually to reduce
- the risk of introducing new bugs.
- <p>
- Note, that development is continued during the ``freeze''
- period, since a new ``unstable'' distribution will be
- created at that time.
- <p>
- In summary, there is always a <em/stable/ and an
- <em/unstable/ distribution available and the <em/frozen/
- distribution shows up for a month from time to time.
- <p>
-
- <sect>Release code names
- <p>
- Every released Debian distribution has a <em/code name/:
- Debian 1.1 is called <em/buzz/, Debian 1.2 <em/rex/, Debian
- 1.3 <em/bo/, Debian 2.0 <em/hamm/, etc.
- <p>
- Since the Debian has an open development (i.e. everyone can
- participate and follow the development) even the
- ``development versions'' (unstable) are distributed via the
- Internet on the Debian FTP server. This FTP server is
- mirrored by lots of other systems. Thus, if we'd call the
- directory which contains the development version simply
- `unstable', then we would have to rename it to `stable' when
- the version is released, which would cause all FTP mirrors
- to re-get the whole distribution (which is already very
- large!).
- <p>
- On the other hand, if we would call the distribution
- directories <em>Debian-x.y</em> from the beginning, people
- would think that Debian release <em>x.y</> is
- available. (This happened in the past, where a CD-ROM vendor
- built a Debian 1.0 CD-ROM based on a pre-1.0 development
- version. That's the reason why the first official Debian
- release was 1.1, and not 1.0.)
- <p>
- Thus, the names of the distribution directories in the
- archive should stay the same during the development period
- and after the release but there may be symbolic links, which
- can be changed.
- <p>
- That's why the distribution directories use the <em/code
- names/ and there are symbolic links <em/stable/,
- <em/unstable/, <em/frozen/, etc. which point to the
- appriopriate release directories.
- <p>
-
- <chapt>Package uploads<p>
+ <sect1>Stable, unstable, and sometimes frozen
+ <p>
+There is always a distribution called <em/stable/ (residing in
+<tt>dists/stable</tt>) and one called <em/unstable/ (residing in
+<tt>dists/unstable</tt>. This reflects the development process of the
+Debian project.
+ <p>
+The ``development'' is done in the <em/unstable/ distribution (that's
+why this distribution is sometimes called <em/development
+distribution/). Every Debian developer can update his or her packages in
+this distribution at any time. Thus, the contents of this distribution
+changes from day to day and since no special effort is done to test
+this distribution it's sometimes ``unstable.''
+ <p>
+After about a period of development, the <em/unstable/ distribution is
+copied in a new distribution directory, called <em/frozen/. After
+that, no changes are allowed to the frozen distribution, except bug
+fixes. (That's why it's called ``frozen.'') After another month or a
+little longer, the <em/frozen/ distribution is renamed to <em/stable/,
+overriding the old <em/stable/ distribution, which is removed at that
+time.
+ <p>
+This development cycle is based on the assumption that the
+<em/unstable/ distribution becomes <em/stable/ after passing a period
+of testing as <em/frozen/. Unfortunately, even once a distribution is
+considered <em/stable/, a few bugs inevitably remain--that's why the
+stable distribution is updated every now and then. However, these
+updates are tested very carefully and have to be acknowledged
+individually to reduce the risk of introducing new bugs. You can find
+proposed additions to <em/stable/ in the <tt/proposed-updates/
+directory.
+ <p>
+Note, that development is continued during the ``freeze'' period,
+since a new <em/unstable/ distribution is be created when the older
+<em/unstable/ is moved to <em/frozen/.
+ <p>
+In summary, there is always a <em/stable/ and an <em/unstable/
+distribution available, and the <em/frozen/ distribution shows up for
+a month or so from time to time.
+
+
+ <sect1>Experimental
+ <p>
+The <em/experimental/ distribution is a specialty distribution. It is
+not a full distribution in the same sense that 'stable' and 'unstable'
+are. Instead, it is meant to be a temporary staging area for highly
+experimental software where there's a good chance that the software
+could break your system. Users who download and install packages from
+<em/experimental/ are expected to have been duly warned. In short,
+all bets are off for the <em/experimental/ distribution.
+ <p>
+Developers should be very selective in the use of the
+<em/experimental/ distribution. Even if a package is highly unstable,
+it could well still go into <em/unstable/; just state a few warnings
+in the description. However, if there is a chance that the software
+could do grave damage to a system, it might be better to put it into
+<em/experimental/.
+ <p>
+For instance, an experimental encrypted filesystem should probably go
+into experimental. A new, beta, version of some software which uses
+completely different configuration might go into experimental at the
+maintainer's discretion. New software which isn't likely to damage
+your system can go into <em/unstable/.
+
+
+ <sect id="codenames">Release code names
+ <p>
+Every released Debian distribution has a <em/code name/: Debian 1.1 is
+called <em/buzz/, Debian 1.2 <em/rex/, Debian 1.3 <em/bo/, Debian 2.0
+<em/hamm/, Debian 2.1 will be called <em/slink/, etc. There is also a
+"pseudo-distribution", called <em/sid/, which is
+used to contain packages for architectures which are not yet
+officially supported or released by Debian. are intended to be
+released for some future distribution.
+ <p>
+Since the Debian has an open development model (i.e., everyone can
+participate and follow the development) even the ``development
+versions'' (unstable) are distributed via the Internet on the Debian
+FTP server. This FTP server is mirrored by lots of other
+systems. Thus, if we'd call the directory which contains the
+development version simply `unstable', then we would have to rename it
+to `stable' when the version is released, which would cause all FTP
+mirrors to re-get the whole distribution (which is already very
+large!).
+ <p>
+On the other hand, if we would call the distribution directories
+<em>Debian-x.y</em> from the beginning, people would think that Debian
+release <em>x.y</> is available. (This happened in the past, where a
+CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development
+version. That's the reason why the first official Debian release was
+1.1, and not 1.0.)
+ <p>
+Thus, the names of the distribution directories in the archive should
+stay the same during the development period and after the release but
+there may be symbolic links, which can be changed.
+ <p>
+That's why the distribution directories use the <em/code names/ and
+there are symbolic links <em/stable/, <em/unstable/, <em/frozen/,
+etc., which point to the appriopriate release directories.
+
+
+ <chapt id="upload">Package uploads
<sect>Announcing new packages
<p>
- If you want to create a new package for the Debian
- distribution, you have to send a short email to
- <em/debian-devel/ describing your plans before you upload
- the new package.
- <p>
- This has the following advantages:
-
+If you want to create a new package for the Debian distribution, you
+should first check the <url
+id="http://www.debian.org/doc/prospective-packages.html"
+name="Work-Needing and Prospective Packages (WNPP)"> page. Checking
+the WNPP ensures that no-one is already working on packaging that
+software, and that effort is not duplicated. Assuming no-one else is
+already working on your prospective package, you must then send a
+short email to <email/debian-devel@lists.debian.org/ describing your
+plan to create a new package. You should set the subject of the email
+to "intent to package <var/foobar/", substituting the name of the new
+package for <var/foobar/.
+ <p>
+There are a number of reasons why we ask maintainers to follow these
+steps.
<list compact>
- <item>It helps the (potentially new) maintainer to tap
- into the experience of people on the list, and lets
- them know if any one else is working on it already
- <p>
- <item>It lets other people thinking about working on the
- package know that there already is a volunteer, and
- efforts may be shared
- <p>
- <item>It lets the rest of the maintainers know more about
- the package than the one line description and the
- changelog entry "Initial version" that generally gets
- posted to debian-devel-changes by default
- <p>
- <item>It is helpful to the people who live off unstable
- (and form our first line of testers); we should
- encourage these people
- <p>
- <item>I think the announcements gives us a better feel of
- what is going on, and what is new, in the project.
- <p>
- <item>We should not dismiss anybody who installs from
- unstable and helps us debug our packages as "fools,
- fools, you installed from unstable; you deserve what
- you get"--we derive a certain benefit from the alpha
- testers
- <p>
- <item>If we appreciate alpha testers, than any name
- changes have to be backwards compatible with the
- people who already installed the old package (conflict
- and replace old package name at a minimum)
+ <item>
+It helps the (potentially new) maintainer to tap into the experience
+of people on the list, and lets them know if any one else is working
+on it already.
+
+ <item>
+It lets other people thinking about working on the package know that
+there already is a volunteer, and efforts may be shared. The "intent
+to package" message to <email/debian-devel@lists.debian.org/ will be
+picked up the the WNPP maintainer, and your intention will be
+published in subsequent versions of the WNPP document.
+
+ <item>
+It lets the rest of the maintainers know more about the package than
+the one line description and the changelog entry "Initial version"
+that generally gets posted to <tt/debian-devel-changes/ by default.
+
+ <item>
+It is helpful to the people who live off unstable (and form our first
+line of testers); we should encourage these people.
+
+ <item>
+I think the announcements gives us a better feel of what is going on,
+and what is new, in the project.
+
+ <item>
+We should not dismiss anybody who installs from unstable and helps us
+debug our packages as "fools, fools, you installed from unstable; you
+deserve what you get"--we derive a certain benefit from the alpha
+testers.
+
+ <item>
+If we appreciate alpha testers, than any name changes have to be
+backwards compatible with the people who already installed the old
+package (conflict and replace old package name at a minimum).
</list>
-
- <sect>Uploading a package
- <p>
+
+
+ <sect id="uploading">Uploading a package
<sect1>Generating the changes file
<p>
-
- When a package is uploaded to the Debian FTP archive, it
- must be accompanied by a <tt/.changes/ file which gives
- directions for its handling. This is usually generated by
- <prgn/dpkg-genchanges/.
+When a package is uploaded to the Debian FTP archive, it must be
+accompanied by a <tt/.changes/ file which gives directions for its
+handling. This is usually generated by <prgn/dpkg-genchanges/.
<p>
-
- This file is a control file with the following fields:
- <list compact>
+This file is a control file with the following fields:
+<list compact>
<item><tt/Format/
<item><tt/Date/
<item><tt/Source/
<item><tt/Files/
</list>
<p>
-
- All of them are mandatory for a Debian upload. See the
- list of control fields in the <em/Debian Packaging Manual/
- for the contents of these fields.
+All of them are mandatory for a Debian upload. See the list of
+control fields in the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual"> for the contents of these fields.
<p>
+Notably, the <tt/Distribution/ field, which originates from the
+<tt>debian/changelog</tt> file, should indicate which distribution the
+package is intended for. There are four possible values for this
+field: <em/stable/, <em/unstable/, <em/frozen/, or <em/experimental/;
+these values can also be combined. For instance, if you have a
+crucial security fix release of a package, and the package has not
+diverged between the <em/stable/ and <em/unstable/ distributions, then
+you might put <tt/stable unstable/ in the <tt>debian/changelog</tt>'s
+distribution field. Or, if Debian has been frozen, and you want to
+get a bug-fix release into <em/frozen/, you would set the distribution
+to <tt/frozen unstable/. Note that setting the distribution to
+<tt/stable/ means that the pacakge will be placed into the
+<tt>proposed-updates</tt> directory of the Debian archive for further
+testing, before it is actually included in <em/stable/. Also note
+that it never makes sense to combine the <em/experimental/
+distribution with anything else.
- The first time a version is uploaded which corresponds to
- a particular upstream version the original source tar file
- should be uploaded and included in the <tt/.changes/ file;
- subsequent times the very same tar file should be used to
- build the new diffs and <tt/.dsc/ files, and it need not
- then be uploaded.
<p>
-
- By default <prgn/dpkg-genchanges/ and
- <prgn/dpkg-buildpackage/ will include the original source
- tar-file if and only if the Debian revision part of the
- source version number is <tt/0/ or <tt/1/, indicating a
- new upstream version. This behaviour may be modified by
- using <tt/-sa/ to always include it or <tt/-sd/ to always
- leave it out.
+The first time a version is uploaded which corresponds to a particular
+upstream version the original source tar file should be uploaded and
+included in the <tt/.changes/ file; subsequent times the very same tar
+file should be used to build the new diffs and <tt/.dsc/ files, and it
+need not then be uploaded.
<p>
-
- If no original source is included in the upload then the
- original source tar-file used by <prgn/dpkg-source/ when
- constructing the <tt/.dsc/ file and diff to be uploaded
- <em/must/ be byte-for-byte identical with the one already
- in the archive. If there is some reason why this is not
- the case then the new version of the original source
- should be uploaded, possibly by using the <tt/-sa/ flag.
+By default <prgn/dpkg-genchanges/ and <prgn/dpkg-buildpackage/ will
+include the original source tar-file if and only if the Debian
+revision part of the source version number is <tt/0/ or <tt/1/,
+indicating a new upstream version. This behaviour may be modified by
+using <tt/-sa/ to always include it or <tt/-sd/ to always leave it
+out.
<p>
+If no original source is included in the upload then the original
+source tar-file used by <prgn/dpkg-source/ when constructing the
+<tt/.dsc/ file and diff to be uploaded <em/must/ be byte-for-byte
+identical with the one already in the archive. If there is some
+reason why this is not the case then the new version of the original
+source should be uploaded, possibly by using the <tt/-sa/ flag.
+
- <sect1>Transferring the files to master
+ <sect1 id="upload-checking">Checking the package prior to upload
<p>
- To upload a package, you need a personal account on the
- master server. Just log in via ftp and transfer the
- files to
- `<tt>/home/Debian/ftp/private/project/Incoming</tt>.'
- (You cannot upload to Incoming on master using anonymous
- FTP--you must use your user-name and password.)
+Before you upload your package, you should do basic testing on it.
+Make sure you try the following activities (you'll need to have an
+older version of the Debian package around).
+<list>
+ <item> install the package and make sure the software
+ works
+
+ <item> upgrade the package from an older version to your
+ new version
+
+ <item> downgrade the package to the previous version
+ (this tests the <tt/postrm/ and <tt/prerm/ scripts)
+
+ <item> remove the package
+
+ <item> run <prgn/lintian/ over the package. You can run
+ <prgn/lintian/ as follows: <tt>lintian -v
+ <var>package-NN</var>.changes</tt>. This will check the
+ source package as well as the binary package. If you
+ don't understand the output that <prgn/lintian/
+ generates, try adding the <tt/-i/ switch, which will
+ cause <prgn/lintian/ to output a very verbose
+ description of the problem.
+
+ </list>
+
+
+ <sect1 id="upload-master">Transferring the files to master
<p>
- You may also find the Debian package '<tt>dupload</tt>'
- useful in uploading new packages to master. See the
- '<tt>dupload</tt>' documentation for more information.
+To upload a package, you need a personal account on
+<ftpsite>master.debian.org</ftpsite>. All maintainers should already
+have this account. You can use either <prgn/ssh/ or <prgn/ftp/ to
+transfer the files. In either case, the files need to be placed into
+<ftppath>/home/Debian/ftp/private/project/Incoming</ftppath>. (You
+cannot upload to Incoming on master using anonymous FTP--you must use
+your user-name and password.)
<p>
+You may also find the Debian package <prgn/dupload/ useful when
+uploading packages. This handy program is distributed with defaults
+for uploading via <prgn/ftp/ to <tt/master/, <tt/chiark/, and
+<tt/erlangen/. It can also be configured to use <prgn/ssh/. See
+<manref name="dupload" section="1"> and <manref name="dupload"
+section="5"> for more information.
+
<sect1>Uploads via Chiark
<p>
- If you have a slow network connection to the master
- system, there are two alternatives: You can upload files
- to Incoming via a cron-driven upload queue in Europe on
- ftp.chiark.greenend.org.uk. For details connect to chiark
- using anonymous FTP and read
- <tt>/pub/debian/private/project/README.how-to-upload</tt>.
- <p>
- The program <tt/dupload/ support uploads to chiark, please
- refer to the documentation that comes with the program,
- for details.
+If you have a slow network connection to <tt/master/, there are two
+alternatives: You can upload files to Incoming via a cron-driven
+upload queue in Europe on <tt/chiark/. For details connect to
+<ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP and
+read
+<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
<p>
+The program <tt/dupload/ supports uploads to chiark, please refer to
+the documentation that comes with the program for details.
+
<sect1>Uploads via Erlangen
<p>
- Another cron-driven upload queue is available in Germany:
- Just upload the files via anonymous FTP to
- <tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>.
+Another cron-driven upload queue is available in Germany: just upload
+the files via anonymous FTP to <url
+id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">.
<p>
- The upload must be a complete Debian upload, as you would
- put it into master's incoming, i.e. a <tt/.changes/ files
- along with the other files mentioned in the
- <tt/.changes/. The queue daemon also checks that the
- <tt/.changes/ is correctly PGP-signed by a Debian
- developer, so that no bogus files can find their way to
- master via the queue. Please also make sure that the
- <tt/Maintainer:/ field in the <tt/.changes/ contains
- *your* e-mail address. The address found there is used for
- all replies, just as on master.
+The upload must be a complete Debian upload, as you would put it into
+master's <tt/Incoming/, i.e., a <tt/.changes/ files along with the
+other files mentioned in the <tt/.changes/. The queue daemon also
+checks that the <tt/.changes/ is correctly PGP-signed by a Debian
+developer, so that no bogus files can find their way to master via the
+queue. Please also make sure that the <tt/Maintainer:/ field in the
+<tt/.changes/ contains <em/your/ e-mail address. The address found
+there is used for all replies, just as on master.
<p>
- There's no need to move your files into a second directory
- after the upload as on chiark. And, in any case, you
- should get some mail reply from the queue daemon what
- happened to your upload. Hopefully it should have been
- moved to master, but in case of errors you're notified,
- too.
- <p>
- The program <tt/dupload/ support uploads to erlangen,
- please refer to the documentation that comes with the
- program, for details.
+There's no need to move your files into a second directory after the
+upload as on chiark. And, in any case, you should get some mail reply
+from the queue daemon what happened to your upload. Hopefully it
+should have been moved to master, but in case of errors you're
+notified, too.
<p>
+The program <prgn/dupload/ supports uploads to erlangen, please refer
+to the documentation that comes with the program for details.
+
<sect1>Uploading to the non-us server
<p>
- To upload a package to the <em/non-us/ server you just
- have to transfer the files via anonymous ftp to
- <tt>ftp://nonus.debian.org/pub/debian-non-US/Incoming</tt>.
- Note, that the <tt>.changes</tt> file must have a valid
- PGP signature from one of the keys of the developers
- keyring.
- <p>
+To upload a package to the <em/non-us/ server you just have to
+transfer the files via anonymous ftp to <url
+id="ftp://nonus.debian.org/pub/debian-non-US/Incoming">. Note, that
+the <tt>.changes</tt> file must have a valid PGP signature from one of
+the keys of the developers keyring.
+
<sect>Announcing package uploads
<p>
- When a package is uploaded an announcement should be posted
- to one of the debian-changes lists. The announcement should
- give the (source) package name and version number, and a
- very short summary of the changes, in the <prgn/Subject/
- field, and should contain the PGP-signed <tt/.changes/ file.
- Some additional explanatory text may be added before the
- start of the <tt/.changes/ file.
- <p>
- If a package is released with the <tt/Distribution:/ set to
- <tt/stable/, the announcement is sent to
- <email/debian-changes@lists.debian.org/.
- <p>
- If a package is released with <tt/Distribution:/ set to
- <tt/unstable/, <tt/experimental/, or <tt/frozen/ (when
- present), the announcement should be posted to
- <email/debian-devel-changes@lists.debian.org/ instead.
- <p>
-
- <sect>Interim releases
- <p>
- Under certain circumstances it is necessary for someone
- other than the usual package maintainer to make a release of
- a package. For example, a porter for another architecture
- may have to make some small changes to the source package
- and does not wish to wait with uploading their release until
- the main maintainer has incorporated the patch, or a serious
- security problem may have come to light requiring immediate
- attention.
- <p>
- When a security bug is detected a fixed package should be
- uploaded as soon as possible. In this case, the Debian
- Security Managers should get in contact with the package
- maintainer to make sure a fixed package is uploaded within a
- reasonable time (less than 48 hours). If the package
- maintainer cannot provide a fixed package fast enough or if
- he/she cannot be reached in time, the Security Manager
- may upload a fixed package.
- <p>
- When someone other than the usual maintainer releases a
- package they should add a new component to the
- <var/debian-revision/ component of the version number--that
- is, the portion after the (last) hyphen. This extra
- component will start at <tt/1/. This is to avoid `stealing'
- one of the usual maintainer's version numbers, possibly
- disrupting their work. If there is no <var/debian-revision/
- component in the version number then one should be created,
- starting at <tt/1/.
- <p>
- If it is absolutely necessary for someone other than the
- usual maintainer to make a release based on a new upstream
- version then the person making the release should start with
- the <var/debian-revision/ value <tt/0.1/. The usual
- maintainer of a package should start their
- <var/debian-revision/ numbering at <tt/1/.
- <p>
- Maintainers other than the usual package maintainer should
- make as few changes to the package as possible, and they
- should always send a unified context diff (<tt/diff -u/)
- detailing their changes to the bug tracking system properly
- flagged with the correct package so that the usual
- maintainer is kept aware of the situation. If the
- non-maintainer upload fixes some bugs, the bug reports
- should not be closed. However, the person making the
- non-maintainer release should send a short message to the
- bug tracking system to all the fixed bugs explaining that
- they have been fixed. This way, the maintainer and other
- people will get notified about that.
- <p>
- The normal maintainer should do at least one of
- <list compact>
- <item> apply the diff,
+When a package is uploaded an announcement should be posted to one of
+the debian-changes lists. The announcement should give the (source)
+package name and version number, and a very short summary of the
+changes, in the <em/Subject/ field, and should contain the PGP-signed
+<tt/.changes/ file. Some additional explanatory text may be added
+before the start of the <tt/.changes/ file.
+ <p>
+If a package is released with the <tt/Distribution:/ set to
+<tt/stable/, the announcement is sent to
+<email/debian-changes@lists.debian.org/.
+ <p>
+If a package is released with <tt/Distribution:/ set to <tt/unstable/,
+<tt/experimental/, or <tt/frozen/ (when present), the announcement
+should be posted to <email/debian-devel-changes@lists.debian.org/
+instead.
+ <p>
+If you use dupload, it is clever enough to determine for itself where
+the announcement should go, and will automatically mail the
+announcement.
- <item> read the diff and decide on each part of it
- themselves, or
+ <sect>Notification that a new package has been installed
+ <p>
+The Debian archive maintainers are responsible for handling package
+uploads. For the most part, uploads are automatically handled on a
+daily basis by an archive maintenance tool called <prgn/dinstall/.
+Specifically, updates to existing packages to the `unstable'
+distribution are handled automatically. In other cases, notably new
+packages, placing the uploaded package into the distribution is
+handled manually. When uploads are handled manually, the change to the
+archive may take up to a week to occur (please be patient).
+ <p>
+In any case, you will receive notification indicating that the package
+has been uploaded via email. Please examine this notification
+carefully. Sometimes the "override" file which the archive
+maintainers use to indicate where packages go, is incorrect or
+out-of-sync with your control file. In these cases, you should either
+correct your control file or file a bug against <tt/ftp.debian.org/
+using the BTS.
- <item> if the maintainer decides not to apply the patch
- but to release a new version, read the description of the
- changes to the next upstream version and ensure that they
- fix each problem that was fixed in the non-maintainer
- release.
+ <sect id="nmu">Interim releases
+ <p>
+Under certain circumstances it is necessary for someone other than the
+usual package maintainer to make a release of a package. For example,
+a porter for another architecture may have to make some small changes
+to the source package and does not wish to wait with uploading their
+release until the main maintainer has incorporated the patch, or a
+serious security problem or bug may have come to light requiring
+immediate attention.
+ <p>
+When a security bug is detected a fixed package should be uploaded as
+soon as possible. In this case, the Debian Security Managers should
+get in contact with the package maintainer to make sure a fixed
+package is uploaded within a reasonable time (less than 48 hours). If
+the package maintainer cannot provide a fixed package fast enough or
+if he/she cannot be reached in time, the Security Manager may upload a
+fixed package.
+ <p>
+When someone other than the usual maintainer releases a package they
+should add a new component to the <var/debian-revision/ component of
+the version number--that is, the portion after the (last) hyphen.
+This extra component will start at <tt/1/. This is to avoid
+`stealing' one of the usual maintainer's version numbers, possibly
+disrupting their work. If there is no <var/debian-revision/ component
+in the version number then one should be created, starting at <tt/1/.
+ <p>
+If it is absolutely necessary for someone other than the usual
+maintainer to make a release based on a new upstream version then the
+person making the release should start with the <var/debian-revision/
+value <tt/0.1/. The usual maintainer of a package should start their
+<var/debian-revision/ numbering at <tt/1/.
+ <p>
+Maintainers other than the usual package maintainer should make as few
+changes to the package as possible, and they should always send a
+unified context diff (<tt/diff -u/) detailing their changes to the bug
+tracking system properly flagged with the correct package so that the
+usual maintainer is kept aware of the situation.
+ <p>
+If the non-maintainer upload (as known as an "NMU") fixes some
+existing bugs, the bug reports should not be closed. Technically,
+only the official package maintainer or the original bug submitter are
+allowed to close bugs. However, the person making the non-maintainer
+release should send a short message to the bug tracking system to all
+the fixed bugs explaining that they have been fixed. Using
+<email/control@bugs.debian.org/, the party doing the NMU should also
+set the severity of the bugs fixed in the NMU to "fixed". This
+ensures that everyone knows that the bug was fixed in an NMU; however
+the bug is left open until the changes in the NMU are incorporated
+"officially" into the package by the offical package maintainer.
+ <p>
+The normal maintainer should do at least one of the following:
+ <list compact>
+ <item>
+apply the diff,
+ <item>
+read the diff and decide on each part of it themselves, or
+ <item>
+if the maintainer decides not to apply the patch but to release a new
+version, read the description of the changes to the next upstream
+version and ensure that they fix each problem that was fixed in the
+non-maintainer release.
</list>
<p>
- In addition, the normal maintainer should <em/always/
- include an entry in the changelog file documenting the
- non-maintainer upload.
- <p>
+In addition, the normal maintainer should <em/always/ include an entry
+in the changelog file documenting the non-maintainer upload.
+
<sect>Maintainer changes
<p>
- Periodically, a listing of packages in need of new
- maintainers will be sent to the <tt>debian-devel</>
- list. This list is also available at
- <ftpsite>ftp.debian.org</> in
- <ftppath>/debian/doc/package-developer/prospective-packages.html</>
- If you wish to take over maintenance of any of those
- packages, or if you can no longer maintain the packages you
- have, or you simply want to know if any one is working on a
- new package, send a message to
- <email/override-change@debian.org/.
+Periodically, a listing of packages in need of new maintainers will be
+sent to <email/debian-devel@lists.debian.org</email> list. This list
+is also available at in the Work-Needing and Prospective Packages
+document (WNPP), <url
+id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html">
+and at <url
+id="http://www.debian.org/doc/prospective-packages.html">. If you wish
+to take over maintenance of any of the packages listed in the WNPP, or
+if you can no longer maintain a packages you have, or you simply want
+to know if any one is working on a new package, send a message to
+<email/wnpp@debian.org/.
+ <p>
+If you take over an old package, you probably want to be listed as the
+package's official maintainer in the bug system. This will happen
+automatically once you upload a new version with an updated
+<tt/Maintainer:/ field. If you do not expect to upload a new version
+for a while, send an email to <email/override-change@debian.org/ so
+that bug reports will go to you.
+
+
+ <chapt id="archive-manip">Moving, Removing, Renaming, and Orphaning Packages
+ <p>
+Some archive manipulation operation are not automated in the Debian
+upload process. This chapter gives guidelines in what to do in these
+cases.
+
+ <sect>Moving packages
+ <p>
+Sometimes a package will change either it's section or it's
+subsection. For instance, a package from the `non-free' section might
+be GPL'd in a later version; in this case you should consider moving
+it to `main' or `contrib' (see the <url
+id="http://www.debian.org/doc/debian-policy/" name="Debian Policy
+Manual"> for guidelines).
+ <p>
+In this case, it is sufficient to edit the package control information
+normally and re-upload the package (see the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual"> for
+details). Carefully examine the installation log sent to you when the
+package is installed into the archive. If for some reason the old
+location of the package remains, file a bug against
+<prgn/ftp.debian.org/ asking that the old location be removed. Give
+details on what you did, since it might be a <prgn/dinstall/ bug.
+
+
+ <sect>Removing packages
<p>
- If you take over an old package, you probably want to be
- listed as the package's official maintainer in the bug
- system. This will happen automatically once you upload a new
- version with an updated <tt/Maintainer:/ field. If you do
- not expect to upload a new version for a while, send an
- email to <email/override-change@debian.org/ so that bug
- reports will go to you.
+If for some reason you want to completely remove a package (say, if it
+is an old compatability library which is not longer required), you
+need to file a bug against <prgn/ftp.debian.org/ asking that the
+package be removed. Make sure you indicate which distribution the
+package should be removed from.
<p>
+If in doubt concerning whether a package is disposable, email
+<email/debian-devel@lists.debian.org/ asking for opinions.
+
+
+ <sect>Replacing or renaming packages
+ <p>
+Sometimes you made a mistake naming the package and you need to rename
+it. In this case, you need to follow a two-step process. First, set
+your <tt>debian/control</tt> file to replace and conflict with the
+obsolete name of the package (see the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual"> for details). Once you've uploaded
+that package, and the package has moved into the archive, file a bug
+against <prgn/ftp.debian.org/ asking to remove the package with the
+obsolete name.
+
+
+ <sect>Orphaning a package
+ <p>
+If you can no longer maintain a package, then you should set the
+package maintainer to <tt>Debian QA
+<debian-qa@lists.debian.org></tt> and email
+<email/wnpp@debian.org/ indicating that the package is now orphaned.
+If the package is especially crucial to Debian, you should instead
+email <email/debian-devel@lists.debian.org/ asking for a new
+maintainer.
+
+
+ <chapt id="bug-handling">Handling Bug Reports
+
+ <sect>Monitoring bugs
+ <p>
+If you want to be a good maintainer, you should periodically check the
+<url id="http://www.debian.org/Bugs/" name="Debian bug tracking system
+(BTS)"> for your packages. The BTS contains all the open bugs against
+your packages.
+ <p>
+Maintainers interact with the BTS via email addresses at
+<tt/bugs.debian.org/. Documentation on available commands can be
+found at <url id="http://www.debian.org/Bugs/">, or, if you have
+installed the <prgn/debian-doc/ package, you can look at the local
+files <tt>/usr/doc/debian/bug-*</tt>.
+ <p>
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned. The
+BTS instructions can tell you how to do this. Make sure the bug is
+not already filed against a package. Try to do a good job reporting a
+bug and redirecting it to the proper location. For extra credit, you
+can go through other packages, merging bugs which are reported more
+than once, or setting bug severities to "fixed" when they have already
+been fixed. Note that when you are neither the bug submitter nor the
+package maintainer, you are not empowered to actually close the bug
+(unless you secure permission from the maintainer).
+
+
+ <sect>When bugs are closed by new uploads
+ <p>
+If you fix a bug in your packages, it is your responsibility as the
+package maintainer to close the bug when it has been fixed. However,
+you should not close the bug until the package which fixes the bug has
+been accepted into the Debian archive. Therefore, once you get
+notification that your updated package has been installed into the
+archive, you can and should close the bug in the BTS.
+ <p>
+Again, see the BTS documentation for details on how to do this.
+Often, it's sufficient to mail the <tt/.changes file to
+<email/<var/XXX/-done@bugs.debian.org/, where <var/XXX/ is your bug
+number.
+
+ <sect id="lintian-reports">Lintian reports
+ <p>
+You should periodically get the new <prgn/lintian/ from `unstable' and
+check over all your packages. Alternatively you can check for you're
+maintainer email address at <url id="http://www.debian.org/lintian/">.
+That page, which is updated automatically, contains <prgn/lintian/
+reports against the latest version of the package (usually from
+'unstable') using the latest <prgn/lintian/.
- <chapt>Handling bug reports<p>
<sect>Reporting lots of bugs at once
<p>
- If you report more then 10 bugs on the same topic at once,
- it is recommended that you send a message to debian-devel
- describing your intention before submitting the report. This
- will allow other developers to verify that the bug is a real
- problem. In addition, it will prevent the situation where
- several maintainers start filing the same bug report
- simultaneously.
- <p>
- Note, that when sending lots of bugs on the same subject,
- you should send the bug report to
- <tt/maintonly@bugs.debian.org/ so that the bug report is not
- forwarded to the bug distribution mailing list.
- <p>
-
-</book>
+If you report more then 10 bugs on the same topic at once, it is
+recommended that you send a message to
+<email/debian-devel@lists.debian.org/ describing your intention before
+submitting the report. This will allow other developers to verify that
+the bug is a real problem. In addition, it will prevent the situation
+where several maintainers start filing the same bug report
+simultaneously.
+ <p>
+Note, that when sending lots of bugs on the same subject, you should
+send the bug report to <email/maintonly@bugs.debian.org/ so that the
+bug report is not forwarded to the bug distribution mailing list.
+
+
+ <chapt id="tools">Whirlwind Tour of Debian Maintainer Tools
+ <p>
+This section contains a rough overview of the tools available to
+maintainers. These tools are meant to help convenience developers and
+free their time for critical tasks.
+ <p>
+Some people prefer to use high-level package maintenance tools and
+some do not. Debian is officially agnostic on this issue, other than
+making the attempt to accomodate the reasonable wishes of developers.
+Therefore, this section is not meant to stipulate to anyone which
+tools they should use or how they should go about with their duties of
+maintainership. Nor is it meant to endorse any particular tool to the
+exclusion of a competing tool.
+ <p>
+Most of the descriptions of these packages come from the actual
+package descriptions themselves.
+
+ <sect id="dpkg-dev">
+ <heading><prgn>dpkg-dev</prgn>
+ <p>
+<prgn>dpkg-dev</prgn> contains the tools (including
+<prgn/dpkg-source/) required to unpack, build and upload Debian source
+packages. These utilities contain the fundamental, low-level
+functionality required to create and manipulated packages; as such,
+they are required for any Debian maintainer.
+
+ <sect id="lintian">
+ <heading><prgn>lintian</prgn>
+ <p>
+<prgn>Lintian</prgn> dissects Debian packages and reports bugs and
+policy violations. It contains automated checks for many aspects of
+Debian policy as well as some checks for common errors. The use of
+<prgn>lintian</prgn> has already been discussed in <ref
+id="upload-checking"> and <ref id="lintian-reports">.
+
+ <sect id="debhelper">
+ <heading><prgn>debhelper</prgn>
+ <p>
+<prgn>debhelper</prgn> is a collection of programs that can be used in
+<tt>debian/rules</tt> to automate common tasks related to building
+binary Debian packages. Programs are included to install various files
+into your package, compress files, fix file permissions, integrate
+your package with the Debian menu system.
+ <p>
+Unlike <prgn>debmake</prgn>, <prgn>debhelper</prgn> is broken into
+several small, granular commands which act in a consistent manner. As
+such, it allows a greater granularity of control than
+<prgn>debmake</prgn>.
+
+ <sect id="debmake">
+ <heading><prgn>debmake</prgn>
+ <p>
+<prgn>debmake</prgn>, a pre-cursor to <prgn>debhelper</prgn>, is a
+less granular <tt>debian/rules</tt> assistant. It includes two main
+programs: <prgn>deb-make</prgn>, which can be used to help a
+maintainer convert a regular (non-Debian) source archive into a Debian
+source package; and <prgn>debstd</prgn>, which incorporates in one big
+shot the same sort of automated functions that one finds in
+<prgn>debhelper</prgn>.
+
+ <sect id="cvs-buildpackage">
+ <heading><prgn>cvs-buildpackage</prgn>
+ <p>
+<prgn>cvs-buildpackage</prgn> provides the capability to inject or
+import Debian source packages into a CVS repository, build a Debian
+package from the CVS repository, and helps in integrating upstream
+changes into the repository.
+ <p>
+These utilities provide an infrastructure to facilitate the use of CVS
+by Debian maintainers. This allows one to keep separate CVS branches
+of a package for <em/stable/, <em/unstable/, and possibly
+<em/experimental/ distributions, along with the other benefits of a
+version control system.
+
+ <sect id="dupload">
+ <heading><prgn>dupload</prgn>
+ <p>
+<prgn>dupload</prgn> is a package and a script to automagically upload
+Debian packages to the Debian archive, to log the upload, and to send
+mail about the upload of a package. You can configure it for new
+upload locations or methods.
+
+ </book>
+</debiandoc>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:nil
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->
~ianmdlvl / developers-reference.git / blobdiff