-<!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:
- bugs in upstream versions should be reported upstream!
-
+ - how to be a good non-maintainer
-->
-<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.0, 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>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?
+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/.
+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>
-
- 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.
+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.
+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.
<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/ in the
- <ftppath>/pub/debian/README.non-US</> file.
+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.
+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>
<sect>Registering as a Debian developer
<p>
-
- 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:
-
+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">.
+ <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.
+ <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:
+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.
+ <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.
+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.
+
<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).
+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>
- 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.
+Every new developer is invited to subscribe to that list (see <ref
+id="mailing-lists"> for details).
<p>
-
-
- <chapt>Internet Servers<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.
+
- <sect id="mailing-lists">Mailing lists<p>
+ <chapt>Internet Servers
- 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.
+ <sect id="mailing-lists">Mailing lists
<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.
+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>
- 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/.
+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>
- 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.
+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.
+
+
<sect>The master server
<p>
<sect>The WWW servers
<p>
- <chapt>The Debian Archive<p>
-
+
+ <chapt>The Debian Archive
+
<sect>Overview
<p>
+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/.
- 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 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.
+ <sect>Sections
<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.)
+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>
- 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.
+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>
- Packages in the <em>contrib</> section have to apply to
- the DFSG, but fail other requirements.
+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>
- (The Debian Policy Manual contains a more exact definition
- of the three sections. This is just meant to be an
- introduction.)
+Packages in the <em>contrib</> section have to apply to the DFSG, but
+fail other requirements.
<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.
+(The Debian Policy Manual contains a more exact definition of the
+three sections. This is just meant to be an introduction.)
<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 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.)
- <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.
+ <sect>Architectures
<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.
+
<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.
- 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>Packages
<p>
-
- There are two types of Debian packages, namely <em/source/
- and <em/binary/ 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/.
+ <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.
- 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.'')
+ <sect>Release code names
<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.
+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.
<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.
+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>
- Note, that development is continued during the ``freeze''
- period, since a new ``unstable'' distribution will be
- created at that time.
+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>
- 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.
+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.
- <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>
+
+ <chapt>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.
+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:
+This has the following advantages:
<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.
+
+ <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.
+
+ <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>
<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:
+This file is a control file with the following fields:
<list compact>
<item><tt/Format/
<item><tt/Date/
<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 <em/Debian Packaging Manual/ for the contents of
+these fields.
<p>
-
- 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.
+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.
+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.
- 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.
- <p>
<sect1>Transferring the files to master
<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.)
- <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 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.)
<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.
+
<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 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.
+
<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
+<tt>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 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.
<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.
+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.
+The program <prgn/dupload/ support uploads to erlangen, please refer
+to the documentation that comes with the program, for details.
<p>
<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/.
+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 <tt/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 <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.
+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.
+
<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
+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,
-
- <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.
+ <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/.
- <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.
+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/.
<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>Handling bug reports<p>
+ <chapt>Handling bug reports
<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.
+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 <email/maintonly@bugs.debian.org/ so that the
+bug report is not forwarded to the bug distribution mailing list.
+
-</book>
+ </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