-<!doctype debiandoc system>
-
+<!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>
<!--
- 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.
- -->
-
-<!--
-
- Topics to be included someday:
+ TODO:
- bugs in upstream versions should be reported upstream!
-
+ - porter instructions - - volunteers needed for this x86-centric
+ maintainer!
+ - add information on how to get accounts on different architectures
+ - talk about CVS access
-->
-<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
+ <book>
-<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>ver. &version;, &date;
+ <copyright>
+ <copyrightsummary><p>
+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" name="the GNU website">.
+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">. Neither does this reference detail
+the standards to which Debian software must comply; that information
+can be found 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?
+So, you've read all the documentation, you understand what everything
+in the <package/hello/ example package is for, and you're about to
+Debianize your favourite piece of software. How do you actually
+become a Debian developer so that your work can be incorporated into
+the Project?
+ <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
+an email 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.
+
+
+ <sect>Registering as a Debian developer
<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/.
+Before you decide to register with the Debian Project, you will need
+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>It is not clear to the author why logins on
+<tt>master</tt> cannot be eight characters or greater. If anyone can
+clarify why, I would appreciate it.</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. Remember that the new
+maintainer team usually calls during evening hours to save on long
+distance tolls. Please do not give a work number, unless you are
+generally there in the evening.
+ <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>
<p>
+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>
+Our standard is to use <prgn>pgp</prgn> version 2.x. You can use
+<prgn/pgp/ version 5, if and only if you make an RSA key. Note that
+we are also working with the <prgn/gpg/ team so that we can have a
+free alternative to PGP; however, this may take a little bit of time.
+ <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 key servers.
+ <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>
+Some countries restrict the use of cryptographic software by their
+citizens. This need not impede one's activities as a Debian package
+maintainer however, as it may be perfectly legal to use cryptographic
+products for authentication, rather than encryption purposes (as is
+the case in France). The Debian Project does not require the use of
+cryptography <em/qua/ cryptography in any manner. If you live in a
+country where use of cryptography even for authentication is forbidden
+then please contact us so we can make special arrangements.
+ <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 contain 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) 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
+<package/debian-keyring/ 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 send a followup
+message asking if your original application was received. Do not
+re-send your original application, that will just confuse the
+new-maintainer team. Please be patient, especially near release
+points; mistakes do occasionally happen, and people do sometimes run
+out of volunteer time.
- 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 id="mentors">Debian Mentors
<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.
+A mailing list called <email/debian-mentors@lists.debian.org/ which
+has been set up for novice maintainers who seek help with initial
+packaging and other developer-related issues. Every new developer is
+invited to subscribe to that list (see <ref id="mailing-lists"> for
+details).
<p>
+Those who prefer one-on-one help (e.g., via private email) should
+also post to that list and an experienced developer will volunteer to
+help.
- 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>
+ <chapt id="servers">Mailing Lists and Servers
- 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 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
+<package>doc-debian</package> 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 unless they explicitly request that this be
+done. 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
+(sending the same message to multiple lists) 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/">.
- <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>
+ <sect id="servers-master">The master server
+ <p>
+The master server, <tt/master.debian.org/, holds the canonical copy
+of the Debian archive (excluding the non-U.S. packages). Generally,
+package uploads go to this server; see <ref id="upload">.
+ <p>
+<tt/master.debian.org/ is the canonical location for the Bug Tracking
+System (BTS). If you plan on doing some statistical analysis or
+processing of Debian bugs, this would be the place to do it. Please
+describe your plans on <email/debian-devel@lists.debian.org/ before
+implementing anything, however, to reduce unnecessary duplication of
+effort or wasted processing time.
+ <p>
+All Debian developers have accounts on <tt/master.debian.org/. Please
+take care to protect your password to this machine. Try to avoid
+login or upload methods which send passwords over the Internet in the
+clear.
+ <p>
+If you find a problem with <tt/master.debian.org/ such as disk full,
+suspicious activity, or whatever, send an email to
+<email>debian-admin@debian.org</email>.
- 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
+ <sect id="servers-ftp">The FTP servers
<p>
- <sect>The FTP servers
- <p>
+ <sect id="servers-www">The WWW servers
+ <p>
+The main web server, <tt/www.debian.org/, is also known as
+<tt/va.debian.org/. All developers are given accounts on this
+machine.
+ <p>
+If you have some Debian-specific information which you want to serve
+up on the web, you can do do this by putting material in the
+<tt>public_html</tt> directory under your home directory. You can do
+this on either <tt/va.debian.org/ or <tt/master.debian.org/. Any
+material you put in those areas are accessible via the URLs
+<tt>http://www.debian.org/~<var>user-id</var>/</tt> and
+<tt>http://master.debian.org/~<var>user-id</var>/</tt>, respectively.
+Please do <em>not</em> put any materials on Debian servers which do
+not relate to Debian.
+ <p>
+If you find a problem with the Debian web server, you should generally
+submit a bug against the pseudo-package,
+<package>www.debian.org</package>. First check whether or not someone
+else has already reported the problem on the <url
+id="http://www.debian.org/Bugs/db/pa/lwww.debian.org.html" name="Bug
+Tracking System">.
- <sect>The WWW servers
- <p>
+ <sect id="servers-cvs">The CVS server
+ <p>
+<tt/cvs.debian.org/ is also known as <tt/va.debian.org/, discussed
+above. If you need the use of a publically accessible CVS server, for
+instance, to help coordinate work on a package between many different
+developers, you can request a CVS area on the server. Generally,
+<tt/cvs.debian.org/ offers a combination of local CVS access,
+anonymous client-server read-only access, and full client-server
+access through <prgn>ssh</prgn>.
+ <p>
+To request a CVS area, send a request via email to
+<email>debian-admin@debian.org</email>.
+
+
+ <sect id="servers-mirrors">Mirrors of Debian servers
+ <p>
+The web and FTP servers have several mirrors available. Please do not
+put heavy load on the canonical FTP or web servers. Ideally, the
+canonical servers only mirror out to a first tier of mirrors, and all
+user access is to the mirrors. This allows Debian to better spread
+our bandwidth requirements over several servers and networks. Note
+that newer push mirroring techniques ensure that mirrors are as
+up-to-date as they can be.
+ <p>
+The main web page listing the available public FTP (and, usually,
+HTTP) servers can be found at <url
+id="http://www.debian.org/distrib/ftplist">. More information
+concerning mirrors can be found at <url
+id="http://www.debian.org/devel/mirror/">. This useful page includes
+information and tools which can be helpful if you are interested in
+setting up your own mirror, either for internal or public access.
+ <p>
+Note that mirrors are generally run by third-parties who are
+interested in helping Debian. As such, developers generally do not
+have accounts on these machines.
+
+
+ <chapt id="archive">The Debian Archive
- <chapt>The Debian Archive<p>
-
<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-i386/admin/
+main/binary-i386/base/
+ ...
+main/binary-m68k
+main/binary-m68k/admin/
+main/binary-m68k/base/
+ ...
+main/source/
+main/source/admin/
+main/source/base/
+ ...
+main/disks-i386/
+main/disks-m68k/
+ ...
+
+contrib/
+contrib/binary-all/
+contrib/binary-i386/
+contrib/binary-m68k/
+ ...
+contrib/source/
+
+non-free/
+non-free/binary-all/
+non-free/binary-i386/
+non-free/binary-m68k/
+ ...
+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
+p<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-m68k, 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>official 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 section 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. The above discussion is just 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 greatly from vendor
+to vendor, 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
+(a.k.a. m68k) machines (like Atari and Amiga), MIPS, and PowerPC
+(a.k.a. ppc).
<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. Subections 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 an <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/ (often the
+author of the software). In this case, the <tt/.diff.gz/ contains the
+changes made by the Debian maintainer.
<p>
+The <tt/.dsc/ lists all the files in 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).
+
+ <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 the <em/development
+distribution/). Every Debian developer can update his or her packages in
+this distribution at any time. Thus, the contents of this distribution
+change from day to day and since no special effort is done to test
+this distribution it's sometimes ``unstable.''
+ <p>
+After a period of development, the <em/unstable/ distribution is
+copied in a new distribution directory, called <em/frozen/. When that
+occurs, 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 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 introduced into the archive
+individually to reduce the risk of introducing new bugs. You can find
+proposed additions to <em/stable/ in the <tt/proposed-updates/
+directory. Those packages in <tt/proposed-updates/ that pass muster
+are periodically moved as a batch into the stable distribution and the
+revision level of the stable distribution is incremented (e.g., `1.3'
+becomes `1.3r1', `2.0r2' becomes `2.0r3', and so forth).
+ <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 file system 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, <em/slink/. There is also a
+"pseudo-distribution", called <em/sid/, which is contains packages for
+architectures which are not yet officially supported or released by
+Debian. These architectures are planned to be integrated into the
+mainstream distribution at some future date.
+ <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.
- 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>
+
+ <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>
+The announcements give maintainers and other interested parties 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.
+
</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>
-
- 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.
+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.
<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, or upgrade the
+package from an older version to your new version if a Debian package
+for it already exists.
+
+ <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.
+ <p>
+Normally, a package should <em/not/ be uploaded if it causes lintian
+to emit errors (they will start with <tt/E/).
+ <p>
+For more information on <prgn/lintian/, see <ref id="lintian">.
+ <item>
+Downgrade the package to the previous version (if one exists) -- this
+tests the <tt/postrm/ and <tt/prerm/ scripts.
+
+ <item>
+Remove the package, then reinstall it.
+
+ </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 username and password.)
+ <p>
+<em/Note:/ Do not upload packages containing software that is
+export-controlled by the United States government to <tt/master/.
+This includes almost all cryptographic software, and even software
+that contains "hooks" to cryptographic software, such as electronic
+mail readers that support PGP encryption and authentication. Uploads
+of such software should go to <tt/non-us/ (see below). If you are
+not sure whether U.S. export controls apply to your package, post a
+message to <email/debian-devel@lists.debian.org/ and ask.
<p>
+You may also find the Debian package <package/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</>.
- <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.
+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>
- 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.
+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>
- 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://non-us.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 key-ring.
+
<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>
+On occasion, it is necessary to upload a package to both the <tt/stable/
+and <tt/unstable/ distributions; this is done by putting both distributions
+in the <tt/Distribution:/ line. In such a case the upload announcement
+should go to both of the above mailing lists.
+ <p>
+The <prgn/dupload/ program is clever enough to determine for itself
+where the announcement should go, and will automatically mail the
+announcement. See <ref id="dupload">.
- <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 official 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.
+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 its section or its 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
+<tt/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 for some reason you want to completely remove a package (say, if it
+is an old compatibility library which is not longer required), you
+need to file a bug against <tt/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 <tt/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 <package/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 <package/lintian/ from `unstable' and
+check over all your packages. Alternatively you can check for your
+maintainer email address at the <url
+id="http://www.debian.org/lintian/" name="online lintian report">.
+That report, which is updated automatically, contains <prgn/lintian/
+reports against the latest version of the distribution (usually from
+'unstable') using the latest <package/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 help prevent
+a situation in which 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">Overview 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; any tool
+which gets the job done is fine. 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><package/dpkg-dev/
+ <p>
+<package/dpkg-dev/ 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><package/lintian/
+ <p>
+<package/Lintian/ 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
+<package/lintian/ has already been discussed in <ref
+id="upload-checking"> and <ref id="lintian-reports">.
+
+ <sect id="debhelper">
+ <heading><package/debhelper/
+ <p>
+<package/debhelper/ 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 <package/debmake/, <package/debhelper/ is broken into
+several small, granular commands which act in a consistent manner. As
+such, it allows a greater granularity of control than
+<package/debmake/.
+
+ <sect id="debmake">
+ <heading><package/debmake/
+ <p>
+<package/debmake/, a pre-cursor to <package/debhelper/, 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
+<package/debhelper/.
+
+ <sect id="cvs-buildpackage">
+ <heading><package/cvs-buildpackage/
+ <p>
+<package/cvs-buildpackage/ 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><package/dupload/
+ <p>
+<package/dupload/ 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:
+-->