-<!doctype debiandoc system>
+<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
+ <!-- include version information so we don't have to hard code it
+ within the document -->
+ <!entity % versiondata SYSTEM "version.ent"> %versiondata;
+ <!-- common, language independant entities -->
+ <!entity % commondata SYSTEM "common.ent" > %commondata;
+ <!-- CVS revision of this document -->
+ <!entity cvs-rev "$Revision: 1.90 $">
+ <!-- if you are translating this document, please notate the RCS
+ revision of the developers reference here -->
+ <!--
+ <!entity cvs-en-rev "X.YY">
+ -->
+]>
+<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!
-
+ - add information on how to get accounts on different architectures
+ - talk about CVS access, other ways to submit problems
+ - add information on how you can contribute w/o being an official
+ developer
+ - "official port maintainer" ? (cf. glibc-pre2.1)
-->
-<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 Di Carlo, current maintainer <email>aph@debian.org</email>
+ <author>Christian Schwarz <email>schwarz@debian.org</email>
+ <author>Ian Jackson <email>ijackson@gnu.ai.mit.edu</email>
+ <version>ver. &version;, &date-en;
+ <copyright>
+ <copyrightsummary>
+copyright ©1998 &ndash 2002 Adam Di Carlo</copyrightsummary>
+ <copyrightsummary>
+copyright ©1997, 1998 Christian Schwarz</copyrightsummary>
+ <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 &file-GPL; in
+the &debian-formal; distribution or on the World Wide Web at <url
+id="&url-gpl;" name="the GNU website">. You can also obtain it by
+writing to the &fsf-addr;.
+
+ <toc detail="sect2">
-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>
+ <chapt id="scope">Scope of This Document
+ <p>
+The purpose of this document is to provide an overview of the
+recommended procedures and the available resources for Debian
+developers.
+ <p>
+The procedures 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 ports and interim releases of other
+maintainers' 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-ftp-master">); and a
+discussion of resources which can help maintainers with the quality of
+their packages (<ref id="tools">).
+ <p>
+It should be clear that this reference does not discuss the technical
+details of the Debian package nor how to generate Debian packages.
+Nor does this reference detail the standards to which Debian software
+must comply. All of such information can be found in the <url
+id="&url-debian-policy;" name="Debian Policy Manual">.
+ <p>
+Furthermore, this document is <em>not an expression of formal
+policy</em>. It contains documentation for the Debian system and
+generally agreed-upon best practices. Thus, it is what is called a
+``normative'' document.
- <toc sect>
- <chapt>Applying to Become a Maintainer<p>
+ <chapt id="new-maintainer">Applying to Become a Maintainer
- <sect>Getting started
- <p>
-
- So, you've read all the documentation, you understand what
- everything in the <prgn/hello/ example package is for, and
- you're about to Debianise your favourite package. How do
- you actually become a Debian developer so that your work can
- be incorporated into the Project?
- <p>
-
- Firstly, subscribe to <prgn/debian-devel/ if you haven't
- already. Send the word <tt/subscribe/ in the <em/Subject/
- of a mail to <email/debian-devel-REQUEST@lists.debian.org/.
- In case of problems contact the list administrator at
- <email/listmaster@lists.debian.org/.
- <p>
-
- 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.
- <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.
- <p>
-
- If you live in a country where use of cryptography even for
- authentication is forbidden then please contact us so we can
- make special arrangements. This does not apply in France,
- where I believe only encryption and not authentication is
- forbidden.
- <p>
-
- <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:
-
- <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="getting-started">Getting started
+ <p>
+So, you've read all the documentation, you've gone through the <url
+id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">,
+understand what everything in the <package>hello</package> 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; if you haven't already.
+Send the word <tt>subscribe</tt> in the <em>Subject</em> of an email
+to &email-debian-devel-req;. In case of problems, contact the list
+administrator at &email-listmaster;. More information on available
+mailing lists can be found in <ref id="mailing-lists">.
+ <p>
+You should subscribe and lurk (that is, read without posting) 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;. See <ref
+id="mentors"> for details. The IRC channel <tt>#debian</tt> on the
+Linux People IRC network (e.g., <tt>irc.debian.org</tt>) can also be
+helpful.
- <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.
+When you know how you want to contribute to &debian-formal;, you
+should get in contact with existing Debian maintainers who are working
+on similar tasks. That way, you can learn from experienced developers.
+For example, if you are interested in packaging existing software for
+Debian you should try to get a sponsor. A sponsor will work together
+with you on your package and upload it to the Debian archive once he
+is happy with the packaging work you have done. You can find a sponsor
+by mailing the &email-debian-mentors; mailing list, describing your
+package and yourself and asking for a sponsor (see <ref id="sponsoring">
+for more information on sponsoring). On the other hand, if you are
+interested in porting Debian to alternative architectures or kernels
+you can subscribe to port specific mailing lists and ask there how to
+get started. Finally, if you are interested in documentation or
+Quality Assurance (QA) work you can join maintainers already working on
+these tasks and submit patches and improvements.
+
+
+ <sect id="registering">Registering as a Debian developer
<p>
-
-
- <chapt>Internet Servers<p>
+Before you decide to register with &debian-formal;, you will need to
+read all the information available at the <url id="&url-newmaint;"
+name="New Maintainer's Corner">. It describes exactly the
+preparations you have to do before you can register to become a Debian
+developer.
- <sect id="mailing-lists">Mailing lists<p>
+For example, before you apply, you have to to read the <url
+id="&url-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-formal;. Reading the <url id="&url-gnu-manifesto;" 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, and checking your technical skills. As
+the number of people working on &debian-formal; has grown to over
+&number-of-maintainers; 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 let them upload packages.
+ <p>
+Before you actually register you should have shown that you can do
+competent work and will be a good contributor. You can show this by
+submitting patches through the Bug Tracking System or having a package
+sponsored by an existing maintainer for a while. Also, we expect that
+contributors are interested in the whole project and not just in
+maintaining their own packages. If you can help other maintainers by
+providing further information on a bug or even a patch, then do so!
+ <p>
+Registration requires that you are familiar with Debian's philosophy
+and technical documentation. Furthermore, you need a GPG key which
+has been signed by an existing Debian maintainer. If your GPG key
+is not signed yet, you should try to meet a Debian maintainer in
+person to get your key signed. There's a <url id="&url-gpg-coord;"
+name="GPG Key Signing Coordination page"> which should help you find
+a maintainer close to you (If you cannot find a Debian maintainer
+close to you, there's an alternative way to pass the ID check. You
+can send in a photo ID signed with your GPG key. Having your GPG
+key signed is the preferred way, however. See the
+<url id="&url-newmaint-id;" name="identification page"> for more
+information about these two options.)
- 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.
+If you do not have an OpenPGP key yet, generate one. Every developer
+needs a OpenPGP key in order to sign and verify package uploads. You
+should read the manual for the software you are using, 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. See <ref id="key-maint"> for more
+information on maintaining your public key.
+ <p>
+Debian uses the <prgn>GNU Privacy Guard</prgn> (package
+<package>gnupg</package> version 1 or better) as its baseline standard.
+You can use some other implementation of OpenPGP as well. Note that
+OpenPGP is a open standard based on <url id="&url-rfc2440;" name="RFC
+2440">.
+ <p>
+The recommended public key algorithm for use in Debian development
+work is the DSA (sometimes call ``DSS'' or ``DH/ElGamal''). Other key
+types may be used however. Your key length must be at least 1024
+bits; 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. <prgn>gpg</prgn> does this
+automatically.
+ <p>
+If your public key isn't on public key servers such as &pgp-keyserv;,
+please read the documentation available locally in &file-keyservs;.
+That document contains instructions on how to put your key on the
+public key servers. The New Maintainer Group will put your public key
+on the servers if it isn't already there.
+ <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). &debian-formal; does not require the use of
+cryptography <em>qua</em> 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>
+To apply as a new maintainer, you need an existing Debian maintainer
+to verify your application (an <em>advocate</em>). After you have
+contributed to Debian for a while, and you want to apply to become a
+registered developer, an existing developer with whom you
+have worked over the past months has to express his belief that you
+can contribute to Debian successfully.
+ <p>
+When you have found an advocate, have your GPG key signed and have
+already contributed to Debian for a while, you're ready to apply.
+You can simply register on our <url id="&url-newmaint-apply;"
+name="application page">. After you have signed up, your advocate
+has to confirm your application. When your advocate has completed
+this step you will be assigned an Application Manager who will
+go with you through the necessary steps of the New Maintainer process.
+You can always check your status on the <url id="&url-newmaint-db;"
+name="applications status board">.
+ <p>
+For more details, please consult <url id="&url-newmaint;" name="New
+Maintainer's Corner"> at the Debian web site. Make sure that you
+are familiar with the necessary steps of the New Maintainer process
+before actually applying. If you are well prepared, you can save
+a lot of timer later on.
+
+
+ <sect id="mentors">Debian Mentors and Sponsors
+ <p>
+The mailing list &email-debian-mentors; 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.
+ <p>
+In addition, if you have some packages ready for inclusion in Debian,
+but are waiting for your new maintainer application to go through, you
+might be able find a sponsor to upload your package for you. Sponsors
+are people who are official Debian maintainers, and who are willing to
+critique and upload your packages for you. Sponsorees can request a
+sponsors at <url id="&url-sponsors;">.
+
+
+ <chapt id="developer-duties">Debian Developer's Duties
+
+ <sect id="user-maint">Maintaining Your Debian Information
+ <p>
+There's a LDAP database containing many informations concerning all
+developers, you can access it at <url id="&url-debian-db;">. You can
+update your password (this password is propagated to most of the machines
+that are accessible to you), your address, your country, the latitude and
+longitude of the point where you live, phone and fax numbers, your
+preferred shell, your IRC nickname, your web page and the email that
+you're using as alias for your debian.org email. Most of the information
+is not accessible to the public, for more details about this
+database, please read its online documentation that you can find
+at <url id="&url-debian-db-doc;">.
+ <p>
+You have to keep the information available there up to date.
+
+ <sect id="key-maint">Maintaining Your Public Key
+ <p>
+Be very careful with your private keys. Do not place them on any
+public servers or multiuser machines, such as
+<tt>master.debian.org</tt>. Back your keys up; keep a copy offline.
+Read the documentation that comes with your software; read the <url
+id="&url-pgp-faq;" name="PGP FAQ">.
+ <p>
+If you add signatures to your public key, or add user identities, you
+can update the debian keyring by sending your key to the key server at
+<tt>&keyserver-host;</tt>. If you need to add a completely new key,
+or remove an old key, send mail to &email-debian-keyring;. The same
+key extraction routines discussed in <ref id="registering"> apply.
+ <p>
+You can find a more in-depth discussion of Debian key maintenance in
+the documentation for the <package>debian-keyring</package> package.
+
+ <sect id="inform-vacation">Going On Vacation Gracefully
+ <p>
+Most developers take vacations, and usually this means that they can't
+work for Debian and they can't be reached by email if any problem occurs.
+The other developers need to know that you're on vacation so that they'll
+do whatever is needed when such a problem occurs. Usually this means that
+other developers are allowed to NMU (see <ref id="nmu">) your package if a
+big problem (release critical bugs, security update, ...) occurs while
+you're on vacation.
+ <p>
+In order to inform the other developers, there's two things that you should do.
+First send a mail to &email-debian-private; giving the period of time when
+you will be on vacation. You can also give some special instructions on what to
+do if any problem occurs. Be aware that some people don't care for vacation
+notices and don't want to read them; you should prepend "[VAC] " to the
+subject of your message so that it can be easily filtered.
+ <p>
+Next you should update your information
+available in the Debian LDAP database and mark yourself as ``on vacation''
+(this information is only accessible to debian developers). Don't forget
+to remove the ``on vacation'' flag when you come back!
+
+ <sect id="upstream-coordination">Coordination With Upstream Developers
+ <p>
+A big part of your job as Debian maintainer will be to stay in contact
+with the upstream developers. Debian users will sometimes report bugs
+to the Bug Tracking System that are not specific to Debian. You
+must forward these bug reports to the upstream developers so that
+they can be fixed in a future release. It's not your job to fix
+non-Debian specific bugs. However, if you are able to do so, you are
+encouraged to contribute to upstream development of the package by
+providing a fix for the bug. Debian users and developers will often
+submit patches to fix upstream bugs, and you should evaluate and
+forward these patches upstream.
+ <p>
+If you need to modify the upstream sources in order to build a policy
+conformant package, then you should propose a nice fix to the upstream
+developers which can be included there, so that you won't have to
+modify the sources of the next upstream version. Whatever changes you
+need, always try not to fork from the upstream sources.
+
+ <sect id="rc-bugs">Managing Release Critical Bugs
+ <p>
+Release Critical Bugs (RCB) are all bugs that have severity
+<em>critical</em>, <em>grave</em> or <em>serious</em>.
+Those bugs can delay the Debian release
+and/or can justify the removal of a package at freeze time. That's why
+these bugs need to be corrected as quickly as possible. You must be
+aware that some developers who are part of the <url
+id="&url-debian-qa;" name="Debian Quality Assurance"> effort are
+following those bugs and try to help you whenever they are able. But if
+you can't fix such bugs within 2 weeks, you should either ask for help
+by sending a mail to the Quality Assurance (QA) group
+&email-debian-qa;, or explain your difficulties and present a plan to fix
+them by sending a mail to the proper bug report. Otherwise, people
+from the QA group may want to do a Non-Maintainer Upload (see
+<ref id="nmu">) after trying to contact you (they might not wait as long as
+usual before they do their NMU if they have seen no recent activity from you
+in the BTS).
+
+ <sect id="qa-effort">Quality Assurance Effort
+ <p>
+Even though there is a dedicated group of people for Quality
+Assurance, QA duties are not reserved solely for them. You can
+participate in this effort by keeping your packages as bug-free as
+possible, and as lintian-clean (see <ref id="lintian-reports">) as
+possible. If you do not find that possible, then you should consider
+orphaning some of your packages (see <ref
+id="orphaning">). Alternatively, you may ask the help of other people
+in order to catch up the backlog of bugs that you have (you can ask
+for help on &email-debian-qa; or &email-debian-devel;).
+
+ <sect id="mia-qa">Dealing with unreachable maintainers
+ <p>
+If you notice that a package is lacking maintenance, you should
+make sure the maintainer is active and will continue to work on
+his packages. Try contacting him yourself.
+ <p>
+If you do not get a reply after a few weeks you should collect all
+useful information about this maintainer. Start by logging into
+the <url id="&url-debian-db;" name="Debian Developer's Database">
+and doing a full search to check whether the maintainer is on vacation
+and when he was last seen. Collect any important package names
+he maintains and any Release Critical bugs filled against them.
+ <p>
+Send all this information to &email-debian-qa;, in order to let the
+QA people do whatever is needed.
+
+ <sect>Retiring Gracefully
+ <p>
+If you choose to leave the Debian project, you should make sure you do
+the following steps:
+<enumlist>
+ <item>
+Orphan all your packages, as described in <ref id="orphaning">.
+ <item>
+Send an email about how you are leaving the project to
+&email-debian-private;.
+ <item>
+Notify the Debian key ring maintainers that you are leaving by
+emailing to &email-debian-keyring;.
+ </enumlist>
+
+
+ <chapt id="servers">Mailing Lists, Servers, and Other Machines
+ <p>
+In this chapter you will find a very brief road map of the Debian
+mailing lists, the main Debian servers, and other Debian machines
+which may be available to you as a developer.
+
+ <sect id="mailing-lists">Mailing lists
+ <p>
+The mailing list server is at <tt>&lists-host;</tt>. Mail
+<tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
+<tt>debian-<var>foo</var></tt> is the name of the list, with the word
+<tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
+<tt>unsubscribe</tt> to unsubscribe. More detailed instructions on
+how to subscribe and unsubscribe to the mailing lists can be found at
+<url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;">
+or locally in &file-mail-lists; 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</tt>) to the original poster unless they explicitly
+request to be copied. Anyone who posts to a mailing list should read
+it to see the responses.
+ <p>
+The following are the core Debian mailing lists: &email-debian-devel;,
+&email-debian-policy;, &email-debian-user;, &email-debian-private;,
+&email-debian-announce;, and &email-debian-devel-announce;. All
+developers are expected to be subscribed to at least
+&email-debian-devel-announce;. There are
+other mailing lists available for a variety of special topics; see
+<url id="&url-debian-lists-subscribe;"> for a list. Cross-posting
+(sending the same message to multiple lists) is discouraged.
+ <p>
+&email-debian-private; is a special mailing list 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; unless it is really necessary. Moreover, do
+<em>not</em> forward email from that list to anyone. Archives of this
+list are not available on the web for obvious reasons, but you can see
+them using your shell account <tt>master.debian.org</tt> and looking
+in the <file>~debian/archive/debian-private</file> directory.
+ <p>
+&email-debian-email; is a special mailing list used as a grab-bag
+for Debian related correspondence such as contacting upstream authors
+about licenses, bugs, etc. or discussing the project with others where it
+might be useful to have the discussion archived somewhere.
+ <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="&url-lists-archives;">.
+
+
+ <sect id="server-machines">Debian servers
+ <p>
+Debian servers are well known servers which serve critical functions
+in the Debian project. Every developer should know what these servers
+are and what they do.
+ <p>
+If you have a problem with the operation of a Debian server, and you
+think that the system operators need to be notified of this problem,
+please find the contact address for the particular machine at <url
+id="&url-devel-machines;">. If you have a non-operating problems
+(such as packages to be remove, suggestions for the web site, etc.),
+generally you'll report a bug against a ``pseudo-package''. See <ref
+id="submit-bug"> for information on how to submit bugs.
+
+ <sect1 id="servers-master">The master server
+ <p>
+<tt>master.debian.org</tt> 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; 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</tt>.
+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</tt> such as disk
+full, suspicious activity, or whatever, send an email to
+&email-debian-admin;.
+
+ <sect1 id="servers-ftp-master">The ftp-master server
<p>
-
- <sect>The master server
+The ftp-master server, <tt>ftp-master.debian.org</tt> (or
+<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
+archive (excluding the non-US packages). Generally, package uploads
+go to this server; see <ref id="upload">.
<p>
+Problems with the Debian FTP archive generally need to be reported as
+bugs against the <package>ftp.debian.org</package> pseudo-package or
+an email to &email-ftpmaster;, but also see the procedures in
+<ref id="archive-manip">.
- <sect>The FTP servers
- <p>
+ <sect1 id="servers-www">The WWW server
+ <p>
+The main web server, <tt>www.debian.org</tt>, is also known as
+<tt>klecker.debian.org</tt>. 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 this by putting material in the
+<file>public_html</file> directory under your home directory. You should
+do this on <tt>klecker.debian.org</tt>. Any material you put in those areas
+are accessible via the URL
+<tt>http://people.debian.org/~<var>user-id</var>/</tt>.
+You should only use this particular location because it will be backed up,
+whereas on other hosts it won't. Please do not put any material on Debian
+servers not relating to Debian, unless you have prior permission.
+Send mail to &email-debian-devel; if you have any questions.
+ <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://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
- <sect>The WWW servers
- <p>
- <chapt>The Debian Archive<p>
-
- <sect>Overview
+ <sect1 id="servers-cvs">The CVS server
<p>
+<tt>cvs.debian.org</tt> is also known as <tt>klecker.debian.org</tt>,
+discussed above. If you need to use 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.
+ <p>
+Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS
+access, anonymous client-server read-only access, and full
+client-server access through <prgn>ssh</prgn>. Also, the CVS area can
+be accessed read-only via the Web at <url id="&url-cvsweb;">.
+ <p>
+To request a CVS area, send a request via email to
+&email-debian-admin;. Include the name of the requested CVS area,
+Debian account should own the CVS root area, and why you need it.
- 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.
+ <sect1 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
+its 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="&url-debian-mirrors;">. More
+information concerning Debian mirrors can be found at <url
+id="&url-debian-mirroring;">. 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.
+
+
+ <sect id="other-machines">Other Debian Machines
+ <p>
+There are other Debian machines which may be made available to you.
+You can use these for Debian-related purposes as you see fit. Please
+be kind to system administrators, and do not use up tons and tons of
+disk space, network bandwidth, or CPU without first getting the
+approval of the local maintainers. Usually these machines are run by
+volunteers. Generally, these machines are for porting activities.
+ <p>
+Aside from the servers mentioned in <ref id="server-machines">, there
+is a list of machines available to Debian developers at <url
+id="&url-devel-machines;">.
+
+
+
+ <chapt id="archive">The Debian Archive
+
+ <sect>Overview
<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 &debian-formal; distribution consists of a lot of Debian packages
+(<tt>.deb</tt>'s, currently around &number-of-pkgs;) and a few
+additional files (documentation, installation disk images, etc.).
<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.
+Here is an example directory tree of a complete Debian archive:
<p>
- Packages in the <em>contrib</> section have to apply to
- the DFSG, but fail other requirements.
+&sample-dist-dirtree;
<p>
- (The Debian Policy Manual contains a more exact definition
- of the three sections. This is just meant to be an
- introduction.)
+As you can see, the top-level directory contains two directories,
+<tt>dists/</tt> and <tt>pool/</tt>. The latter is a ``pool'' in which the
+packages actually are, and which is handled by the archive maintenance
+database and the accompanying programs. The former contains the
+distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
+Each of those distribution directories is divided in equivalent
+subdirectories purpose of which is equal, so we will only explain how it
+looks in stable. The <tt>Packages</tt> and <tt>Sources</tt> files in the
+distribution subdirectories can reference files in the <tt>pool/</tt>
+directory.
<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.
+<tt>dists/stable</tt> contains three directories, namely <em>main</em>,
+<em>contrib</em>, and <em>non-free</em>.
<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.)
+In each of the areas, there is a directory with the source packages
+(<tt>source</tt>), a directory for each supported architecture
+(<tt>binary-i386</tt>, <tt>binary-m68k</tt>, etc.), and a directory
+for architecture independent packages (<tt>binary-all</tt>).
<p>
-
- <sect>Architectures
+The <em>main</em> area contains additional directories which holds
+the disk images and some essential pieces of documentation required
+for installing the Debian distribution on a specific architecture
+(<tt>disks-i386</tt>, <tt>disks-m68k</tt>, etc.).
<p>
+The <em>binary-*</em> and <em>source</em> directories are divided
+further into <em>subsections</em>.
- 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.
- <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.
- <p>
- <sect>Sub sections
+ <sect>Sections
<p>
+The <em>main</em> section of the Debian archive is what makes up the
+<strong>official &debian-formal; distribution</strong>. The
+<em>main</em> section is official because it fully complies with all
+our guidelines. The other two sections do not, to different degrees;
+as such, they are <strong>not</strong> officially part of
+&debian-formal;.
+ <p>
+Every package in the main section must fully comply with the <url
+id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and
+with all other policy requirements as described in the <url
+id="&url-debian-policy;" name="Debian Policy Manual">. The DFSG is
+our definition of ``free software.'' Check out the Debian Policy
+Manual for details.
+ <p>
+Packages in the <em>contrib</em> section have to comply with the DFSG,
+but may fail other requirements. For instance, they may depend on
+non-free packages.
+ <p>
+Packages which do not apply to the DFSG are placed in the
+<em>non-free</em> 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 <url id="&url-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</em> and <em>contrib</em> sections, one can avoid any legal
+risks. Some packages in the <em>non-free</em> 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</em> and include as
+many on the CD-ROMs as he's allowed to. (Since this varies greatly from
+vendor to vendor, this job can't be done by the Debian developers.)
- 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.
+
+ <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 x86, DEC Alpha, SPARC, Motorola
+680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC. The
+Linux 2.2 kernel supports even more architectures, including ARM and
+UltraSPARC. Since Linux supports these platforms, Debian decided that
+it should, too. Therefore, Debian has ports underway; in fact, we
+also have ports underway to non-Linux kernel. Aside from
+<em>i386</em> (our name for Intel x86), there is <em>m68k</em>,
+<em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>,
+and <em>arm</em>, as of this writing.
+ <p>
+&debian-formal; 1.3 is only available as <em>i386</em>. Debian 2.0
+shipped for <em>i386</em> and <em>m68k</em> architectures. Debian 2.1
+ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and
+<em>sparc</em> architectures. Debian 2.2 adds support for the
+<em>powerpc</em> and <em>arm</em> architectures.
+ <p>
+Information for developers or uses about the specific ports are
+available at the <url id="&url-debian-ports;" name="Debian Ports web
+pages">.
+
+
+ <sect>Subsections
+ <p>
+The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
+are split into <em>subsections</em> to simplify the installation
+process and the maintainance of the archive. Subsections are not
+formally defined, except perhaps the `base' subsection.
+Subsections simply exist to simplify the organization and browsing of
+available packages. Please check the current Debian distribution to
+see which sections are available.
+ <p>
+Note however that with the introduction of package pools (see the top-level
+<em>pool/</em> directory), the subsections in the form of subdirectories
+will eventually cease to exist. They will be kept in the packages' `Section'
+header fields, though.
<sect>Packages
<p>
+There are two types of Debian packages, namely <em>source</em> and
+<em>binary</em> packages.
+ <p>
+Source packages consist of either two or three files: a <tt>.dsc</tt>
+file, and either a <tt>.tar.gz</tt> file or both an
+<tt>.orig.tar.gz</tt> and a <tt>.diff.gz</tt> file.
+ <p>
+If a package is developed specially for Debian and is not distributed
+outside of Debian, there is just one <tt>.tar.gz</tt> file which
+contains the sources of the program. If a package is distributed
+elsewhere too, the <tt>.orig.tar.gz</tt> file stores the so-called
+<em>upstream source code</em>, that is the source code that's
+distributed from the <em>upstream maintainer</em> (often the author of
+the software). In this case, the <tt>.diff.gz</tt> contains the
+changes made by the Debian maintainer.
+ <p>
+The <tt>.dsc</tt> lists all the files in the source package together
+with checksums (<prgn>md5sums</prgn>) and some additional info about
+the package (maintainer, version, etc.).
- 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.
- <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.
- <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.
- <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.).
- <p>
<sect>Distribution directories
<p>
+The directory system described in the previous chapter is itself
+contained within <em>distribution directories</em>. Each
+distribution is actually contained in the <tt>pool</tt> directory in the
+top-level of the Debian archive itself.
+ <p>
+To summarize, the Debian archive has a root directory within an FTP
+server. For instance, at the mirror site,
+<ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is
+contained in <ftppath>/debian</ftppath>, which is a common location
+(another is <tt>/pub/debian</tt>).
+ <p>
+A distribution is comprised of Debian source and binary packages, and the
+respective <tt>Sources</tt> and <tt>Packages</tt> index files, containing
+the header information from all those packages. The former are kept in the
+<tt>pool/</tt> directory, while the latter are kept in the <tt>dists/</tt>
+directory of the archive (because of backwards compatibility).
+
- 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>
-
- <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:
-
+ <sect1 id="sec-dists">Stable, testing, and unstable
+ <p>
+There are always distributions called <em>stable</em> (residing in
+<tt>dists/stable</tt>), one called <em>testing</em> (residing in
+<tt>dists/testing</tt>), and one called <em>unstable</em> (residing in
+<tt>dists/unstable</tt>). This reflects the development process of the
+Debian project.
+ <p>
+Active development is done in the <em>unstable</em> distribution
+(that's why this distribution is sometimes called the <em>development
+distribution</em>). 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. Since no special effort is done
+to make sure everything in this distribution is working properly, it is
+sometimes ``unstable.''
+ <p>
+Packages get copied from <em>unstable</em> to <em>testing</em> if they
+satisfy certain criteria. To get into <em>testing</em> distribution, a
+package needs to be in the archive for two weeks and not have any
+release critical bugs. After that period, it will propagate into
+<em>testing</em> as soon as anything it depends on is also added. This
+process is automatic. You can see some notes on this system as well
+as <tt>update_excuses</tt> (describing which packages are valid
+candidates, which are not, and why not) at <url
+id="&url-testing-maint;">.
+ <p>
+After a period of development, once the release manager deems fit, the
+<em>testing</em> distribution is frozen, meaning that the policies
+which control how packages move from <em>unstable</em> to testing are
+tightened. Packages which are too buggy are removed. No changes are
+allowed into <em>testing</em> except for bug fixes. After some time
+has elapsed, depending on progress, the <em>testing</em> distribution
+goes into a `deep freeze', when no changes are made to it except those
+needed for the installation system. This is called a ``test cycle'',
+and it can last up to two weeks. There can be several test cycles,
+until the distribution is prepared for release, as decided by the
+release manager. At the end of the last test cycle, the
+<em>testing</em> distribution is renamed to <em>stable</em>,
+overriding the old <em>stable</em> distribution, which is removed at
+that time (although it can be found at <tt>&archive-host;</tt>).
+ <p>
+This development cycle is based on the assumption that the
+<em>unstable</em> distribution becomes <em>stable</em> after passing a
+period of being in <em>testing</em>. Even once a distribution is
+considered stable, a few bugs inevitably remain &mdash 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</em> in the
+<tt>proposed-updates</tt> directory. Those packages in
+<tt>proposed-updates</tt> 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 under <em>unstable</em> continues during the
+``freeze'' period, since the <em>unstable</em> distribution remains in
+place in parallel with <em>testing</em>.
+
+ <sect1>Experimental
+ <p>
+The <em>experimental</em> distribution is a specialty distribution.
+It is not a full distribution in the same sense as `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, or software that's just too unstable
+even for the <em>unstable</em> distribution (but there is a reason to
+package it nevertheless). Users who download and install
+packages from <em>experimental</em> are expected to have been duly
+warned. In short, all bets are off for the <em>experimental</em>
+distribution.
+ <p>
+If there is a chance that the software could do grave damage to a system,
+it is likely to be better to put it into <em>experimental</em>.
+For instance, an experimental compressed file system should probably go
+into <em>experimental</em>.
+ <p>
+Whenever there is a new upstream version of a package that introduces new
+features but breaks a lot of old ones, it should either not be uploaded, or
+be uploaded to <em>experimental</em>. A new, beta, version of some software
+which uses completely different configuration can go into
+<em>experimental</em>, at the maintainer's discretion. If you are working
+on an incompatible or complex upgrade situation, you can also use
+<em>experimental</em> as a staging area, so that testers can get early
+access.
+ <p>
+Some experimental software can still go into <em>unstable</em>, with a few
+warnings in the description, but that isn't recommended because packages
+from <em>unstable</em> are expected to propagate to <em>testing</em> and
+thus to <em>stable</em>.
+ <p>
+New software which isn't likely to damage your system can go directly into
+<em>unstable</em>.
+ <p>
+An alternative to <em>experimental</em> is to use your personal web space
+on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
+
+
+ <sect id="codenames">Release code names
+ <p>
+Every released Debian distribution has a <em>code name</em>: Debian
+1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
+`hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; and Debian 3.0, `woody'. There is also
+a ``pseudo-distribution'', called `sid', which is the current
+`unstable' distribution; since packages are moved from `unstable' to
+`testing' as they approach stability, `sid' itself is never released.
+As well as the usual contents of a Debian distribution, `sid' 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 Debian has an open development model (i.e., everyone can
+participate and follow the development) even the `unstable' and `testing'
+distributions are distributed to the Internet through the Debian FTP and
+HTTP server network. Thus, if we had called the directory which contains
+the release candidate version `testing', then we would have to rename it
+to `stable' when the version is released, which would cause all FTP
+mirrors to re-retrieve the whole distribution (which is quite large).
+ <p>
+On the other hand, if we called the distribution directories
+<em>Debian-x.y</em> from the beginning, people would think that Debian
+release <em>x.y</em> 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 are
+determined by their code names and not their release status (e.g.,
+`slink'). These names stay the same during the development period and
+after the release; symbolic links, which can be changed easily,
+indicate the currently released stable distribution. That's why the
+real distribution directories use the <em>code names</em>, while
+symbolic links for <em>stable</em>, <em>testing</em>, and
+<em>unstable</em> point to the appropriate release directories.
+
+
+ <chapt id="upload">Package Uploads
+
+ <sect>New packages
+ <p>
+If you want to create a new package for the Debian distribution, you
+should first check the <url id="&url-wnpp;" name="Work-Needing and
+Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that
+no one is already working on packaging that software, and that effort is
+not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for
+more information.
+ <p>
+Assuming no one else is already working on your prospective package,
+you must then submit a bug report (<ref id="submit-bug">) against the
+pseudo package <tt>wnpp</tt>
+describing your plan to create a new package, including, but not
+limiting yourself to, a description of the package, the license of the
+prospective package and the current URL where it can be downloaded
+from.
+ <p>
+You should set the subject of the bug to ``ITP: <var>foo</var>
+-- <var>short description</var>'', substituting the name of the new
+package for <var>foo</var>. The severity of the bug report must be set
+to <em>wishlist</em>. If you feel it's necessary, send a copy to
+&email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header
+of the message (no, don't use <tt>CC:</tt>, because that way the message's subject
+won't indicate the bug number).
+ <p>
+Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry on the
+changelog of the new package in order for the bug report to be
+automatically closed once the new package is installed on the archive
+(<ref id="upload-bugfix">).
+ <p>
+There are a number of reasons why we ask maintainers to announce their
+intentions:
<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 anyone else is working
+on it already.
+ <item>
+It lets other people thinking about working on the package know that
+there already is a volunteer, so efforts may be shared.
+ <item>
+It lets the rest of the maintainers know more about the package than
+the one line description and the usual changelog entry ``Initial release''
+that gets posted to <tt>debian-devel-changes</tt>.
+ <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.
</list>
-
- <sect>Uploading a package
- <p>
- <sect1>Generating the changes file
+ <sect id="changelog-entries">
+ <heading>Adding an entry to <file>debian/changelog</file></heading>
<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/.
+Changes that you make to the package need to be recorded in the
+<file>debian/changelog</file>. These changes should provide a concise
+description of what was changed, why (if it's in doubt), and note if
+any bugs were closed. They also record when the package was
+completed. This file will be installed in
+<file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>, or
+<file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native
+packages.
<p>
+The <file>debian/changelog</file> file conform to a certain structure,
+with a number of different fields. One field of note, the
+<em>distribution</em>, is described in <ref id="upload-dist">. More
+information about the structure of this file can be found in
+the Debian Policy section titled "<file>debian/changelog</file>".
+ <p>
+Changelog entries can be used to automatically close Debian bugs when
+the package is installed into the archive. See <ref
+id="upload-bugfix">.
+ <p>
+It is conventional that the changelog entry notating of a package that
+contains a new upstream version of the software looks like this:
+<example>
+ * new upstream version
+</example>
+ <p>
+There are tools to help you create entries and finalize the
+<file>changelog</file> for release — see <ref id="devscripts">
+and <ref id="dpkg-dev-el">.
+
- This file is a control file with the following fields:
- <list compact>
- <item><tt/Format/
- <item><tt/Date/
- <item><tt/Source/
- <item><tt/Binary/
- <item><tt/Architecture/
- <item><tt/Version/
- <item><tt/Distribution/
- <item><tt/Urgency/
- <item><tt/Maintainer/
- <item><tt/Description/
- <item><tt/Changes/
- <item><tt/Files/
+
+ <sect id="upload-checking">Checking the package prior to upload
+ <p>
+Before you upload your package, you should do basic testing on it. At
+a minimum, you should try the following activities (you'll need to
+have an older version of the same 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</prgn> over the package. You can run
+<prgn>lintian</prgn> as follows: <tt>lintian -v
+<var>package-version</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</prgn> generates, try adding the <tt>-i</tt>
+switch, which will cause <prgn>lintian</prgn> to output a very verbose
+description of the problem.
+ <p>
+Normally, a package should <em>not</em> be uploaded if it causes lintian
+to emit errors (they will start with <tt>E</tt>).
+ <p>
+For more information on <prgn>lintian</prgn>, see <ref id="lintian">.
+ <item>
+Downgrade the package to the previous version (if one exists) — this
+tests the <tt>postrm</tt> and <tt>prerm</tt> scripts.
+ <item>
+Remove the package, then reinstall it.
</list>
+
+
+ <sect>Generating the changes file
+ <p>
+When a package is uploaded to the Debian FTP archive, it must be
+accompanied by a <tt>.changes</tt> file, which gives directions to the
+archive maintainers for its handling. This is usually generated by
+<prgn>dpkg-genchanges</prgn> during the normal package build process.
+ <p>
+The changes file is a control file with the following fields:
+ <p>
+&control-file-fields;
+ <p>
+All of these fields are mandatory for a Debian upload. See the list
+of control fields in the <url id="&url-debian-policy;" name="Debian
+Policy Manual"> for the contents of these fields. You can close bugs
+automatically using the <tt>Description</tt> field, see <ref
+id="upload-bugfix">.
+
+
+ <sect1>The original source tarball
+ <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</tt> file. Subsequently, this very same
+tar file should be used to build the new diffs and <tt>.dsc</tt>
+files, and will not need to be re-uploaded.
+ <p>
+By default, <prgn>dpkg-genchanges</prgn> and
+<prgn>dpkg-buildpackage</prgn> will include the original source tar
+file if and only if the Debian revision part of the source version
+number is 0 or 1, indicating a new upstream version. This behaviour
+may be modified by using <tt>-sa</tt> to always include it or
+<tt>-sd</tt> to always leave it out.
+ <p>
+If no original source is included in the upload, the original
+source tar-file used by <prgn>dpkg-source</prgn> when constructing the
+<tt>.dsc</tt> file and diff to be uploaded <em>must</em> be
+byte-for-byte identical with the one already in the archive. If there
+is some reason why this is not the case, the new version of the
+original source should be uploaded, possibly by using the <tt>-sa</tt>
+flag.
+
+
+ <sect1 id="upload-dist">Picking a distribution
+ <p>
+The <tt>Distribution</tt> field, which originates from the first line of
+the <file>debian/changelog</file> file, indicates which distribution the
+package is intended for.
+ <p>
+There are three possible values for this field: `stable', `unstable',
+and `experimental'. Normally, packages are uploaded into
+<em>unstable</em>.
<p>
+You should avoid combining `stable' with others because of potential
+problems with library dependencies (for your package and for the package
+built by the build daemons for other architecture).
+See <ref id="upload-stable"> for more information on when and how to
+upload to <em>stable</em>.
+ <p>
+It never makes sense to combine the <em>experimental</em> distribution
+with anything else.
+
+<!--
+ <sect2 id="upload-frozen">Uploading to <em>frozen</em>
+ <p>
+The Debian freeze is a crucial time for Debian. It is our chance to
+synchronize and stabilize our distribution as a whole. Therefore,
+care must be taken when uploading to <em>frozen</em>.
+ <p>
+It is tempting to always try to get the newest release of software
+into the release. However, it's much more important that the system
+as a whole is stable and works as expected.
+ <p>
+The watchword for uploading to <em>frozen</em> is <strong>no new
+code</strong>. This is a difficult thing to quantify, so here are
+some guidelines:
+ <p>
+<list>
+ <item>
+Fixes for bugs of severity <em>critical</em>, <em>grave</em>, or
+<em>serious</em> severity are always allowed for those packages that
+must exist in the final release
+ <item>
+<em>critical</em>, <em>grave</em>, and <em>serious</em> bug fixes are
+allowed for non-necessary packages but only if they don't add any new
+features
+ <item>
+important, normal and minor bug fixes are allowed (though discouraged)
+on all packages if and only if there are no new features
+ <item>
+wishlist fixes are not allowed (they are, after all, not really bugs)
+ <item>
+documentation bug fixes are allowed, since good documentation is
+important
+ </list>
+ <p>
+Experience has shown that there is statistically a 15% chance that
+every bug fix will introduce a new bug. The introduction and
+discovery of new bugs either delays release or weakens the final
+product. There is little correlation between the severity of the
+original bug fixed and the severity of the bug newly introduced by the
+fix.
+
+ -->
+
+
+ <sect2 id="upload-stable">Uploading to <em>stable</em>
+ <p>
+Uploading to <em>stable</em> means that the package 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</em>.
+ <p>
+Extra care should be taken when uploading to <em>stable</em>. Basically, a
+package should only be uploaded to stable if one of the following happens:
+<list>
+ <item>a security problem (e.g. a Debian security advisory)
+ <item>a truely critical functionality problem
+ <item>the package becomes uninstallable
+ <item>a released architecture lacks the package
+</list>
+ <p>
+It is discouraged to change anything else in the package that isn't
+important, because even trivial fixes can cause bugs later on. Uploading
+new upstream versions to fix security problems is deprecated; applying the
+specific patch from the new upstream version to the old one ("backporting"
+the patch) is the right thing to do in most cases.
+ <p>
+Packages uploaded to <em>stable</em> need to be compiled on systems running
+<em>stable</em>, so that their dependencies are limited to the libraries
+(and other packages) available in <em>stable</em>; for example, a package
+uploaded to <em>stable</em> that depends on a library package that only
+exists in unstable will be rejected. Making changes to dependencies of other
+packages (by messing with <tt>Provides</tt> or shlibs files), possibly making
+those other packages uninstallable, is strongly discouraged.
+ <p>
+The Release Team (which can be reached at &email-debian-release;) will
+regularly evaluate the uploads in <em>proposed-updates</em> and decide if
+your package can be included in <em>stable</em>. Please be clear (and
+verbose, if necessary) in your changelog entries for uploads to
+<em>stable</em>, because otherwise the package won't be considered for
+inclusion.
+
+
+
+ <sect id="uploading">Uploading a package
- 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.
+ <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
<p>
+To upload a package, you need a personal account on
+<ftpsite>ftp-master.debian.org</ftpsite>, which you should have as an
+official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
+to transfer the files, place them into <tt>&us-upload-dir;</tt>;
+if you use anonymous FTP to upload, place them into
+<ftppath>/pub/UploadQueue/</ftppath>. Please note that you should transfer
+the changes file last. Otherwise, your upload may be rejected because the
+archive maintenance software will parse the changes file and see that not
+all files have been uploaded. If you don't want to bother with transfering
+the changes file last, you can simply copy your files to a temporary
+directory on <tt>ftp-master</tt> and then move them to
+<tt>&us-upload-dir;</tt>.
+ <p>
+<em>Note:</em> Do not upload to <tt>ftp-master</tt> packages
+containing software that is patent-restricted by the United States
+government, nor any cryptographic packages which belong to
+<em>contrib</em> or <em>non-free</em>. If you can't upload it to
+<tt>ftp-master</tt>, then neither can you upload it to the overseas
+upload queues on <tt>chiark</tt> or <tt>erlangen</tt>. Uploads of
+such software should go to <tt>non-us</tt> (see <ref
+id="upload-non-us">). If you are not sure whether U.S. patent
+controls or cryptographic controls apply to your package, post a
+message to &email-debian-devel; and ask.
+ <p>
+You may also find the Debian packages <package>dupload</package> or
+<package>dput</package> useful
+when uploading packages. These handy program are distributed with
+defaults for uploading via <prgn>ftp</prgn> to <tt>ftp-master</tt>,
+<tt>chiark</tt>, and <tt>erlangen</tt>. They can also be configured to
+use <prgn>ssh</prgn> or <prgn>rsync</prgn>. See <manref name="dupload"
+section="1">, <manref name="dupload" section="5"> and <manref name="dput"
+section="1"> for more information.
+ <p>
+After uploading your package, you can check how the archive maintenance
+software will process it by running <prgn>dinstall</prgn> on your changes
+file: <example>dinstall -n foo.changes</example>
- 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.
+ <sect1 id="upload-non-us">Uploading to <tt>non-US</tt> (pandora)
+ <p>
+As discussed above, export controlled software should not be uploaded
+to <tt>ftp-master</tt>. Instead, upload the package to
+<ftpsite>non-us.debian.org</ftpsite>, placing the files in
+<tt>&non-us-upload-dir;</tt> (both <ref id="dupload"> and <ref
+id="dput"> can be used also, with the right invokation). By default,
+you can use the same account/password that works on
+<tt>ftp-master</tt>. If you use anonymous FTP to upload, place the
+files into <ftppath>/pub/UploadQueue/</ftppath>.
+ <p>
+You can check your upload the same way it's done on <tt>ftp-master</tt>,
+with:
+<example>dinstall -n foo.changes</example>
+ <p>
+Note that U.S. residents or citizens are subject to restrictions on
+export of cryptographic software. As of this writing, U.S. citizens
+are allowed to export some cryptographic software, subject to
+notification rules by the U.S. Department of Commerce. However, this
+restriction has been waived for software which is already available
+outside the U.S. Therefore, any cryptographic software which belongs
+in the <em>main</em> section of the Debian archive and does not depend
+on any package outside of <em>main</em> (e.g., does not depend on
+anything in <em>non-US/main</em>) can be uploaded to <tt>ftp-master</tt>
+or its queues, described above.
<p>
+Debian policy does not prevent upload to non-US by U.S. residents or
+citizens, but care should be taken in doing so. It is recommended that
+developers take all necessary steps to ensure that they are not
+breaking current US law by doing an upload to non-US, <em>including
+consulting a lawyer</em>.
+ <p>
+For packages in <em>non-US/main</em>, <em>non-US/contrib</em>,
+developers should at least follow the <url id="&url-u.s.-export;"
+name="procedure outlined by the US Government">. Maintainers of
+<em>non-US/non-free</em> packages should further consult the <url
+id="&url-notification-of-export;" name="rules on notification of
+export"> of non-free software.
+ <p>
+This section is for information only and does not constitute legal
+advice. Again, it is strongly recommended that U.S. citizens and
+residents consult a lawyer before doing uploads to non-US.
- 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.
+
+ <sect1>Uploads via <tt>chiark</tt>
+ <p>
+If you have a slow network connection to <tt>ftp-master</tt>, there are
+alternatives. One is to upload files to <tt>Incoming</tt> via a
+upload queue in Europe on <tt>chiark</tt>. For details connect to
+<url id="&url-chiark-readme;">.
<p>
+<em>Note:</em> Do not upload packages containing software that is
+export-controlled by the United States government to the queue on
+<tt>chiark</tt>. Since this upload queue goes to <tt>ftp-master</tt>, the
+prescription found in <ref id="upload-ftp-master"> applies here as well.
+ <p>
+The program <prgn>dupload</prgn> comes with support for uploading to
+<tt>chiark</tt>; please refer to the documentation that comes with the
+program for details.
+
- 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>Uploads via <tt>erlangen</tt>
+ <p>
+Another upload queue is available in Germany: just upload the files
+via anonymous FTP to <url id="&url-upload-erlangen;">.
+ <p>
+The upload must be a complete Debian upload, as you would put it into
+<tt>ftp-master</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files
+along with the other files mentioned in the <tt>.changes</tt>. The
+queue daemon also checks that the <tt>.changes</tt> is correctly
+PGP-signed by a Debian developer, so that no bogus files can find
+their way to <tt>ftp-master</tt> via this queue. Please also make sure that
+the <tt>Maintainer</tt> field in the <tt>.changes</tt> contains
+<em>your</em> e-mail address. The address found there is used for all
+replies, just as on <tt>ftp-master</tt>.
+ <p>
+There's no need to move your files into a second directory after the
+upload, as on <tt>chiark</tt>. And, in any case, you should get a
+mail reply from the queue daemon explaining what happened to your
+upload. Hopefully it should have been moved to <tt>ftp-master</tt>, but in
+case of errors you're notified, too.
<p>
+<em>Note:</em> Do not upload packages containing software that is
+export-controlled by the United States government to the queue on
+<tt>erlangen</tt>. Since this upload queue goes to <tt>ftp-master</tt>, the
+prescription found in <ref id="upload-ftp-master"> applies here as well.
+ <p>
+The program <prgn>dupload</prgn> comes with support for uploading to
+<tt>erlangen</tt>; please refer to the documentation that comes with
+the program for details.
+
- <sect1>Transferring the files to master
+ <sect1>Other Upload Queues
<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.)
+Another upload queue is available which is based in the US, and is a
+good backup when there are problems reaching <tt>ftp-master</tt>. You can
+upload files, just as in <tt>erlangen</tt>, to <url
+id="&url-upload-samosa;">.
<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.
- <p>
-
- <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.
- <p>
-
- <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.
- <p>
- There's no need to move your files into a second directory
- after the upload as on chiark. And, in any case, you
- should get some mail reply from the queue daemon what
- happened to your upload. Hopefully it should have been
- moved to master, but in case of errors you're notified,
- too.
- <p>
- The program <tt/dupload/ support uploads to erlangen,
- please refer to the documentation that comes with the
- program, for details.
- <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>
-
- <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,
+An upload queue is available in Japan: just upload the files via
+anonymous FTP to <url id="&url-upload-jp;">.
+
+
+
+ <sect id="upload-announce">Announcing package uploads
+ <p>
+When a package is uploaded, an announcement should be posted to one of
+the ``debian-changes'' lists. This is now done automatically by the archive
+maintenance software when it runs (usually once a day). You just need to use
+a recent <package>dpkg-dev</package> (>= 1.4.1.2). The mail generated by
+the archive maintenance software will contain the PGP/GPG signed
+<tt>.changes</tt> files that you uploaded with your package.
+Previously, <prgn>dupload</prgn> used to send those announcements, so
+please make sure that you configured your <prgn>dupload</prgn> not to
+send those announcements (check its documentation and look for
+``dinstall_runs'').
+ <p>
+If a package is released with the <tt>Distribution:</tt> set to
+`stable', the announcement is sent to &email-debian-changes;. If a
+package is released with <tt>Distribution:</tt> set to `unstable',
+or `experimental', the announcement will be
+posted to &email-debian-devel-changes; instead.
+ <p>
+The <prgn>dupload</prgn> program is clever enough to determine
+where the announcement should go, and will automatically mail the
+announcement to the right list. See <ref id="dupload">.
+
+ <sect id="upload-notification">
+ <heading>Notification that a new package has been installed</heading>
+ <p>
+The Debian archive maintainers are responsible for handling package
+uploads. For the most part, uploads are automatically handled on a
+daily basis by the archive maintenance tools, <prgn>katie</prgn>.
+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 month to occur. Please be
+patient.
+ <p>
+In any case, you will receive email notification indicating that the
+package has added to the archive, which also indicates which bugs will
+be closed by the upload. Please examine this notification carefully,
+checking if any bugs you meant to close didn't get triggered.
+ <p>
+The installation notification also includes information on what
+section the package was inserted into. If there is a disparity, you
+will receive a separate email notifying you of that. Read on below.
+
+ <sect1 id="override-file">The override file
+ <p>
+The <file>debian/control</file> file's <tt>Section</tt> and
+<tt>Priority</tt> fields do not actually specify where the file will
+be placed in the archive, nor its priority. In order to retain the
+overall integrity of the archive, it is the archive maintainers who
+have control over these fields. The values in the
+<file>debian/control</file> file are actually just hints.
+ <p>
+The archive maintainers keep track of the canonical sections and
+priorities for packages in the <em>override file</em>. If there is a
+disparity between the <em>override file</em> and the package's fields
+as indicated in <file>debian/control</file>, then you will receive an
+email noting the divergence when the package is installed into the
+archive. You can either correct your <file>debian/control</file> file
+for your next upload, or else you may wish to make a change in the
+<em>override file</em>.
+ <p>
+To alter the actual section that a package is put in, you need to
+first make sure that the <file>debian/control</file> in your package
+is accurate. Next, send an email &email-override; or submit a bug
+against <package>ftp.debian.org</package> requesting that the section
+or priority for your package be changed from the old section or
+priority to the new one. Be sure to explain your reasoning.
+ <p>
+For more information about <em>override files</em>, see <manref
+name="dpkg-scanpackages" section="8">, &file-bts-mailing;, and
+&file-bts-info;.
- <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.
+
+ <chapt id="nmu">Non-Maintainer Uploads (NMUs)
+ <p>
+Under certain circumstances it is necessary for someone other than the
+official package maintainer to make a release of a package. This is
+called a non-maintainer upload, or NMU.
+ <p>
+Debian porters, who compile packages for different architectures, do
+NMUs as part of their normal porting activity (see <ref
+id="porting">). Another reason why NMUs are done is when a Debian
+developers needs to fix another developers' packages in order to
+address serious security problems or crippling bugs, especially during
+the freeze, or when the package maintainer is unable to release a fix
+in a timely fashion.
+ <p>
+This chapter contains information providing guidelines for when and
+how NMUs should be done. A fundamental distinction is made between
+source and binary-only NMUs, which is explained in the next section.
+
+ <sect id="nmu-terms">Terminology
+ <p>
+There are two new terms used throughout this section: ``binary-only NMU''
+and ``source NMU''. These terms are used with specific technical
+meaning throughout this document. Both binary-only and source NMUs are
+similar, since they involve an upload of a package by a developer who
+is not the official maintainer of that package. That is why it's a
+<em>non-maintainer</em> upload.
+ <p>
+A source NMU is an upload of a package by a developer who is not the
+official maintainer, for the purposes of fixing a bug in the package.
+Source NMUs always involves changes to the source (even if it is just
+a change to <file>debian/changelog</file>). This can be either a
+change to the upstream source, or a change to the Debian bits of the
+source. Note, however, that source NMUs may also include
+architecture-dependent packages, as well as an updated Debian diff
+(or, more rarely, new upstream source as well).
+ <p>
+A binary-only NMU is a recompilation and upload of a binary package
+for a given architecture. As such, it is usually part of a porting
+effort. A binary-only NMU is a non-maintainer uploaded binary version
+of a package, with no source changes required. There are many cases
+where porters must fix problems in the source in order to get them to
+compile for their target architecture; that would be considered a
+source NMU rather than a binary-only NMU. As you can see, we don't
+distinguish in terminology between porter NMUs and non-porter NMUs.
+ <p>
+Both classes of NMUs, source and binary-only, can be lumped by the
+term ``NMU''. However, this often leads to confusion, since most
+people think ``source NMU'' when they think ``NMU''. So it's best to
+be careful. In this chapter, if we use the unqualified term ``NMU'',
+we refer to any type of non-maintainer upload NMUs, whether source and
+binary, or binary-only.
+
+
+ <sect id="nmu-who">Who can do an NMU
+ <p>
+Only official, registered Debian maintainers can do binary or source
+NMUs. An official maintainer is someone who has their key in the
+Debian key ring. Non-developers, however, are encouraged to download
+the source package and start hacking on it to fix problems; however,
+rather than doing an NMU, they should just submit worthwhile patches
+to the Bug Tracking System. Maintainers almost always appreciate
+quality patches and bug reports.
+
+
+ <sect id="nmu-when">When to do a source NMU
+ <p>
+Guidelines for when to do a source NMU depend on the target
+distribution, i.e., stable, unstable, or experimental. Porters have
+slightly different rules than non-porters, due to their unique
+circumstances (see <ref id="source-nmu-when-porter">).
+ <p>
+When a security bug is detected, a fixed package should be uploaded
+as soon as possible. In this case, the Debian security officers 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, a security officer may upload a fixed
+package (i.e., do a source NMU).
+ <p>
+During the release cycle (see <ref id="sec-dists">), NMUs which fix
+serious or higher severity bugs are encouraged and accepted. Even
+during this window, however, you should endeavor to reach the current
+maintainer of the package; they might be just about to upload a fix
+for the problem. As with any source NMU, the guidelines found in <ref
+id="nmu-guidelines"> need to be followed.
+ <p>
+Bug fixes to unstable by non-maintainers are also acceptable, but only
+as a last resort or with permission. Try the following steps first,
+and if they don't work, it is probably OK to do an NMU:
+ <p>
+<list>
+ <item>
+Make sure that the package bug is in the Debian Bug Tracking System
+(BTS). If not, submit a bug.
+ <item>
+Email the maintainer, and offer to help fix the package bug. Give it a
+few days.
+ <item>
+Go ahead and fix the bug, submitting a patch to the right bug in the
+BTS. Build the package and test it as discussed in <ref
+id="upload-checking">. Use it locally.
+ <item>
+Wait a couple of weeks for a response.
+ <item>
+Email the maintainer, asking if it is OK to do an NMU.
+ <item>
+Double check that your patch doesn't have any unexpected side effects.
+Make sure your patch is as small and as non-disruptive as it can be.
+ <item>
+Wait another week for a response.
+ <item>
+Go ahead and do the source NMU, as described in <ref
+id="nmu-guidelines">.
</list>
+
+
+
+ <sect id="nmu-guidelines">How to do a source NMU
+ <p>
+The following applies to porters insofar as they are playing the dual
+role of being both package bug-fixers and package porters. If a
+porter has to change the Debian source archive, automatically their
+upload is a source NMU and is subject to its rules. If a porter is
+simply uploading a recompiled binary package, the rules are different;
+see <ref id="porter-guidelines">.
+ <p>
+First and foremost, it is critical that NMU patches to source should
+be as non-disruptive as possible. Do not do housekeeping tasks, do
+not change the name of modules or files, do not move directories; in
+general, do not fix things which are not broken. Keep the patch as
+small as possible. If things bother you aesthetically, talk to the
+Debian maintainer, talk to the upstream maintainer, or submit a bug.
+However, aesthetic changes must <em>not</em> be made in a non-maintainer
+upload.
+
+
+ <sect1 id="nmu-version">Source NMU version numbering
+ <p>
+Whenever you have made a change to a package, no matter how trivial,
+the version number needs to change. This enables our packing system
+to function.
+ <p>
+If you are doing a non-maintainer upload (NMU), you should add a new
+minor version number to the <var>debian-revision</var> part of the
+version number (the portion after the last hyphen). This extra minor
+number will start at `1'. For example, consider the package `foo',
+which is at version 1.1-3. In the archive, the source package control
+file would be <file>foo_1.1-3.dsc</file>. The upstream version is
+`1.1' and the Debian revision is `3'. The next NMU would add a new
+minor number `.1' to the Debian revision; the new source control file
+would be <file>foo_1.1-3.1.dsc</file>.
+ <p>
+The Debian revision minor number is needed to avoid stealing one of
+the package maintainer's version numbers, which might disrupt their
+work. It also has the benefit of making it visually clear that a
+package in the archive was not made by the official maintainer.
+ <p>
+If there is no <var>debian-revision</var> component in the version
+number then one should be created, starting at `0.1'. 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</var> value
+`0.1'. The usual maintainer of a package should start their
+<var>debian-revision</var> numbering at `1'. Note that if you do
+this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
+<tt>-sa</tt> switch to force the build system to pick up the new
+source package (normally it only looks for Debian revisions of '0' or
+'1' — it's not yet clever enough to know about `0.1').
+ <p>
+Remember, porters who are simply recompiling a package for a different
+architecture do not need to renumber. Porters should use new version
+numbers if and only if they actually have to modify the source package
+in some way, i.e., if they are doing a source NMU and not a binary
+NMU.
+
+
+ <sect1 id="nmu-changelog">
+ <heading>Source NMUs must have a new changelog entry</heading>
+ <p>
+A non-maintainer doing a source NMU must create a changelog entry,
+describing which bugs are fixed by the NMU, and generally why the NMU
+was required and what it fixed. The changelog entry will have the
+non-maintainer's email address in the log entry and the NMU version
+number in it.</p>
+ <p>
+By convention, source NMU changelog entries start with the line
+<example>
+ * Non-maintainer upload
+</example></p></sect1>
+
+
+ <sect1 id="nmu-patch">Source NMUs and the Bug Tracking System
+ <p>
+Maintainers other than the official package maintainer should make as
+few changes to the package as possible, and they should always send a
+patch as a unified context diff (<tt>diff -u</tt>) detailing their
+changes to the Bug Tracking System.
+ <p>
+What if you are simply recompiling the package? In this case, the
+process is different for porters than it is for non-porters, as
+mentioned above. If you are not a porter and are doing an NMU that
+simply requires a recompile (i.e., a new shared library is available
+to be linked against, a bug was fixed in
+<package>debhelper</package>), there must still be a changelog entry;
+therefore, there will be a patch. If you are a porter, you are
+probably just doing a binary-only NMU. (Note: this leaves out in the cold
+porters who have to do recompiles — chalk it up as a weakness in how
+we maintain our archive.)
+ <p>
+If the source NMU (non-maintainer upload) fixes some existing bugs,
+these bugs should be tagged <em>fixed</em> in the Bug Tracking
+System rather than closed. By convention, only the official package
+maintainer or the original bug submitter are allowed to close bugs.
+Fortunately, Debian's archive system recognizes NMUs and thus marks
+the bugs fixed in the NMU appropriately if the person doing the NMU
+has listed all bugs in the changelog with the <tt>Closes:
+bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for
+more information describing how to close bugs via the changelog).
+Tagging the bugs <em>fixed</em> 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>
+Also, after doing an NMU, you have to open a new bug and include a
+patch showing all the changes you have made. The normal maintainer
+will either apply the patch or employ an alternate method of fixing
+the problem. Sometimes bugs are fixed independently upstream, which
+is another good reason to back out an NMU's patch. If the maintainer
+decides not to apply the NMU's patch but to release a new version,
+the maintainer needs to ensure that the new upstream version really
+fixes each problem that was fixed in the non-maintainer release.
+ <p>
+In addition, the normal maintainer should <em>always</em> retain the
+entry in the changelog file documenting the non-maintainer upload.
+
+
+ <sect1 id="nmu-build">Building source NMUs
+ <p>
+Source NMU packages are built normally. Pick a distribution using the
+same rules as found in <ref id="upload-dist">. Just as described in
+<ref id="uploading">, a normal changes file, etc., will be built. In
+fact, all the prescriptions from <ref id="upload"> apply, including
+the need to announce the NMU to the proper lists.
+ <p>
+Make sure you do <em>not</em> change the value of the maintainer in
+the <file>debian/control</file> file. Your name as given in the NMU entry of
+the <file>debian/changelog</file> file will be used for signing the
+changes file.
+
+
+
+
+ <chapt id="porting">Porting and Being Ported
+ <p>
+Debian supports an ever-increasing number of architectures. Even if
+you are not a porter, and you don't use any architecture but one, it
+is part of your duty as a maintainer to be aware of issues of
+portability. Therefore, even if you are not a porter, you should read
+most of this chapter.
+ <p>
+Porting is the act of building Debian packages for architectures that
+is different from the original architecture of the package
+maintainer's binary package. It is a unique and essential activity.
+In fact, porters do most of the actual compiling of Debian packages.
+For instance, for a single <em>i386</em> binary package, there must be
+a recompile for each architecture, which is amounts to
+&number-of-arches; more builds.
+
+
+ <sect id="kind-to-porters">Being Kind to Porters
+ <p>
+Porters have a difficult and unique task, since they are required to
+deal with a large volume of packages. Ideally, every source package
+should build right out of the box. Unfortunately, this is often not
+the case. This section contains a checklist of ``gotchas'' often
+committed by Debian maintainers — common problems which often stymie
+porters, and make their jobs unnecessarily difficult.
+ <p>
+The first and most important watchword is to respond quickly to bug or
+issues raised by porters. Please treat porters with courtesy, as if
+they were in fact co-maintainers of your package (which in a way, they
+are). Please be tolerant of succinct or even unclear bug reports,
+doing your best to hunt down whatever the problem is.
+ <p>
+By far, most of the problems encountered by porters are caused by
+<em>packaging bugs</em> in the source packages. Here is a checklist
+of things you should check or be aware of.
+
+<enumlist>
+ <item>
+Make sure that your <tt>Build-Depends</tt> and
+<tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>
+are set properly. The best way to validate this is to use the
+<package>debootstrap</package> package to create an unstable chroot
+environment. Within that chrooted environment, install the
+<package>build-essential</package> package and any package
+dependancies mention in <tt>Build-Depends</tt> and/or
+<tt>Build-Depends-Indep</tt>. Finally, try building your package
+within that chrooted environment.
+ <p>
+See the <url id="&url-debian-policy;" name="Debian Policy
+Manual"> for instructions on setting build dependencies.
+ <item>
+Don't set architecture to a value other than ``all'' or ``any'' unless
+you really mean it. In too many cases, maintainers don't follow the
+instructions in the <url id="&url-debian-policy;" name="Debian Policy
+Manual">. Setting your architecture to ``i386'' is usually incorrect.
+ <item>
+Make sure your source package is correct. Do <tt>dpkg-source -x
+<var>package</var>.dsc</tt> to make sure your source package unpacks
+properly. Then, in there, try building your package from scratch with
+<tt>dpkg-buildpackage</tt>.
+ <item>
+Make sure you don't ship your source package with the
+<file>debian/files</file> or <file>debian/substvars</file> files.
+They should be removed by the `clean' target of
+<file>debian/rules</file>.
+ <item>
+Make sure you don't rely on locally installed or hacked configurations
+or programs. For instance, you should never be calling programs in
+<file>/usr/local/bin</file> or the like. Try not to rely on programs
+be setup in a special way. Try building your package on another
+machine, even if it's the same architecture.
+ <item>
+Don't depend on the package you're building already being installed (a
+sub-case of the above issue).
+ <item>
+Don't rely on the compiler being a certain version, if possible. If
+not, then make sure your build dependencies reflect the restrictions,
+although you are probably asking for trouble, since different
+architectures sometimes standardize on different compilers.
+ <item>
+Make sure your debian/rules contains separate ``binary-arch'' and
+``binary-indep'' targets, as the Debian Packaging Manual requires.
+Make sure that both targets work independently, that is, that you can
+call the target without having called the other before. To test this,
+try to run <tt>dpkg-buildpackage -b</tt>.
+ </enumlist>
+
+
+ <sect id="porter-guidelines">Guidelines for Porter Uploads
+ <p>
+If the package builds out of the box for the architecture to be ported
+to, you are in luck and your job is easy. This section applies to
+that case; it describes how to build and upload your binary-only NMU so
+that it is properly installed into the archive. If you do have to
+patch the package in order to get it to compile for the other
+architecture, you are actually doing a source NMU, so consult <ref
+id="nmu-guidelines"> instead.
+ <p>
+In a binary-only NMU, no real changes are being made to the source. You do
+not need to touch any of the files in the source package. This
+includes <file>debian/changelog</file>.
+ <p>
+The way to invoke <prgn>dpkg-buildpackage</prgn> is as
+<tt>dpkg-buildpackage -B -e<var>porter-email</var></tt>. Of course,
+set <var>porter-email</var> to your email address. This will do a
+binary-only build of only the architecture-dependant portions of the
+package, using the `binary-arch' target in <file>debian/rules</file>.
+
+ <sect1 id="recompile-nmu-versioning">
+ <heading>Recompilation Binary-Only NMU Versioning</heading>
+ <p>
+Sometimes you need to recompile a package against other packages which
+have been updated, such as libraries. You do have to bump the version
+number in this case, so that the version comparison system can
+function properly. Even so, these are considered binary-only NMUs
+— there is no need in this case to trigger all other
+architectures to consider themselves out of date or requiring
+recompilation.
+ <p>
+Such recompilations require special ``magic'' version numbering, so that
+the archive maintenance tools recognize that, even though there is a
+new Debian version, there is no corresponding source update. If you
+get this wrong, the archive maintainers will reject your upload (due
+to lack of corresponding source code).
+ <p>
+The ``magic'' for a recompilation-only NMU is triggered by using the
+third-level number on the Debian part of the version. For instance,
+if the latest version you are recompiling against was version
+``2.9-3'', your NMU should carry a version of ``2.9-3.0.1''. If the
+latest version was ``3.4-2.1'', your NMU should have a version number
+of ``3.4-2.1.1''.
+
+
+ <sect1 id="source-nmu-when-porter">
+ <heading>When to do a source NMU if you are a porter</heading>
+ <p>
+Porters doing a source NMU generally follow the guidelines found in
+<ref id="nmu">, just like non-porters. However, it is expected that
+the wait cycle for a porter's source NMU is smaller than for a
+non-porter, since porters have to cope with a large quantity of
+packages.
+Again, the situation varies depending on the distribution they are
+uploading to.
+
+<!--
+FIXME: commented out until I can work out how to upload to testing directly
+
+ Crucial fixes (i.e., changes need to get a source
+package to compile for a released-targeted architecture) can be
+uploaded with <em>no</em> waiting period for the `frozen' distribution.
+ -->
+ <p>
+However, if you are a porter doing an NMU for `unstable', the above
+guidelines for porting should be followed, with two variations.
+Firstly, the acceptable waiting period &mdash the time between when the
+bug is submitted to the BTS and when it is OK to do an NMU — is seven
+days for porters working on the unstable distribution. This period
+can be shortened if the problem is critical and imposes hardship on
+the porting effort, at the discretion of the porter group. (Remember,
+none of this is Policy, just mutually agreed upon guidelines.)
+ <p>
+Secondly, porters doing source NMUs should make sure that the bug they
+submit to the BTS should be of severity `serious' or greater. This
+ensures that a single source package can be used to compile every
+supported Debian architecture by release time. It is very important
+that we have one version of the binary and source package for all
+architecture in order to comply with many licenses.
+ <p>
+Porters should try to avoid patches which simply kludge around bugs in
+the current version of the compile environment, kernel, or libc.
+Sometimes such kludges can't be helped. If you have to kludge around
+compilers bugs and the like, make sure you <tt>#ifdef</tt> your work
+properly; also, document your kludge so that people know to remove it
+once the external problems have been fixed.
+ <p>
+Porters may also have an unofficial location where they can put the
+results of their work during the waiting period. This helps others
+running the port have the benefit of the porter's work, even during
+the waiting period. Of course, such locations have no official
+blessing or status, so buyer, beware.
+
+
+ <sect>Tools for Porters
<p>
- In addition, the normal maintainer should <em/always/
- include an entry in the changelog file documenting the
- non-maintainer upload.
- <p>
+There are several tools available for the porting effort. This section
+contains a brief introduction to these tools; see the package
+documentation or references for full information.
+
+
+ <sect1 id="quinn-diff">
+ <heading><package>quinn-diff</package>
+ <p>
+<package>quinn-diff</package> is used to locate the differences from
+one architecture to another. For instance, it could tell you which
+packages need to be ported for architecture <var>Y</var>, based on
+architecture <var>X</var>.
+
+
+ <sect1 id="buildd">
+ <heading><package>buildd</package>
+ <p>
+The <package>buildd</package> system is used as a distributed,
+client-server build distribution system. It is usually used in
+conjunction with <em>auto-builders</em>, which are ``slave'' hosts
+which simply check out and attempt to auto-build packages which need
+to be ported. There is also an email interface to the system, which
+allows porters to ``check out'' a source package (usually one which
+cannot yet be autobuilt) and work on it.
+ <p>
+<package>buildd</package> is not yet available as a package; however,
+most porting efforts are either using it currently or planning to use
+it in the near future. It collects a number of as yet unpackaged
+components which are currently very useful and in use continually,
+such as <prgn>andrea</prgn>, <prgn>sbuild</prgn> and
+<prgn>wanna-build</prgn>.
+ <p>
+Some of the data produced by <package>buildd</package> which is
+generally useful to porters is available on the web at <url
+id="&url-buildd;">. This data includes nightly updated information
+from <prgn>andrea</prgn> (source dependencies) and
+<package>quinn-diff</package> (packages needing recompilation).
+ <p>
+We are very excited about this system, since it potentially has so
+many uses. Independent development groups can use the system for
+different sub-flavors of Debian, which may or may not really be of
+general interest (for instance, a flavor of Debian built with gcc
+bounds checking). It will also enable Debian to recompile entire
+distributions quickly.
+
+
+ <sect1 id="dpkg-cross">
+ <heading><package>dpkg-cross</package>
+ <p>
+<package>dpkg-cross</package> is a tool for installing libraries and
+headers for cross-compiling in a way similar to
+<package>dpkg</package>. Furthermore, the functionality of
+<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
+enhanced to support cross-compiling.
+
+
+
+
+ <chapt id="archive-manip">
+ <heading>Moving, Removing, Renaming, Adopting, and Orphaning
+ Packages</heading>
+ <p>
+Some archive manipulation operation are not automated in the Debian
+upload process. These procedures should be manually followed by
+maintainers. This chapter gives guidelines in what to do in these
+cases.
- <sect>Maintainer changes
+ <sect>Moving packages
+ <p>
+Sometimes a package will change its section. For instance, a
+package from the `non-free' section might be GPL'd in a later version,
+in which case, the package should be moved to `main' or
+`contrib'.<footnote> See the <url id="&url-debian-policy;"
+name="Debian Policy Manual"> for guidelines on what section a package
+belongs in.
+ </footnote>
+ <p>
+If you need to change the section for one of your packages, change the
+package control information to place the package in the desired
+section, and re-upload the package (see the <url id="&url-debian-policy;"
+name="Debian Policy 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</tt> asking that the old
+location be removed. Give details on what you did, since it might be
+a bug in the archive maintenance software.
+ <p>
+If, on the other hand, you need to change the <em>subsection</em> of
+one of your packages (e.g., ``devel'', ``admin''), the procedure is
+slightly different. Correct the subsection as found in the control
+file of the package, and reupload that. Also, you'll need to get the
+override file updated, as described in <ref id="override-file">.
+
+
+ <sect id="removing-pkgs">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</tt> 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; asking for opinions. Also of interest is the
+<prgn>apt-cache</prgn> program from the <package>apt</package>
+package. When invoked as <tt>apt-cache showpkg
+<var>package</var></tt>, the program will show details for
+<var>package</var>, including reverse depends.
+
+ <sect1>Removing packages from <tt>Incoming</tt>
+ <p>
+In the past, it was possible to remove packages from <tt>incoming</tt>.
+With the introduction of the New Incoming system this is no longer
+possible. Instead, you have to upload a new revision of your package with
+a higher version as the package you want to replace. Both versions will be
+installed in the archive but only the higher version will actually be
+available in <em>unstable</em> since the previous version will immediately
+be replaced by the higher. However, if you do proper testing of your
+packages, the need to replace a package should not occur too often anyway.
+
+ <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 <file>debian/control</file> file to replace and conflict with the
+obsolete name of the package (see the <url id="&url-debian-policy;"
+name="Debian Policy 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</tt> asking to remove the package with the
+obsolete name.
+
+ <sect id="orphaning">Orphaning a package
+ <p>
+If you can no longer maintain a package, you need to inform the others
+about that, and see that the package is marked as orphaned.
+you should set the package maintainer to <tt>Debian QA Group
+&orphan-address;</tt> and submit a bug report
+against the pseudo package <package>wnpp</package>. The bug report should be
+titled <tt>O: <var>package</var> -- <var>short description</var></tt>
+indicating that the package is now orphaned. The severity of the bug
+should be set to <em>normal</em>. If you feel it's necessary, send a copy
+to &email-debian-devel; by putting the address in the X-Debbugs-CC: header
+of the message (no, don't use CC:, because that way the message's subject
+won't indicate the bug number).
+ <p>
+If the package is especially crucial to Debian, you should instead submit
+a bug against <tt>wnpp</tt> and title it <tt>RFA: <var>package</var> --
+<var>short description</var></tt> and set its severity to
+<em>important</em>. Definitely copy the message to debian-devel in this
+case, as described above.
+ <p>
+Read instructions on the <url id="&url-wnpp;" name="WNPP web pages">
+for more information.
+
+ <sect id="adopting">Adopting a package
+ <p>
+A list of packages in need of a new maintainer is available at in the
+<url name="Work-Needing and Prospective Packages list (WNPP)"
+id="&url-wnpp;">. If you wish to take over maintenance of any of the
+packages listed in the WNPP, please take a look at the aforementioned
+page for information and procedures.
+ <p>
+It is not OK to simply take over a package that you feel is neglected
+— that would be package hijacking. You can, of course, contact the
+current maintainer and ask them if you may take over the package.
+However, without their assent, you may not take over the package.
+Even if they ignore you, that is still not grounds to take over a
+package. If you really feel that a maintainer has gone AWOL (absent
+without leave), post a query to &email-debian-private;.
+ <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:</tt> field, although it can take a few hours after the
+upload is done. If you do not expect to upload a new version for a while,
+send an email to &email-override; so that bug reports will go to you
+right away.
+
+
+
+ <chapt id="bug-handling">Handling Bugs
+
+ <sect>Monitoring bugs
+ <p>
+If you want to be a good maintainer, you should periodically check the
+<url id="&url-bts;" 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</tt>. Documentation on available commands can be
+found at <url id="&url-bts;">, or, if you have installed the
+<package>doc-debian</package> package, you can look at the local files
+&file-bts-docs;.
+ <p>
+Some find it useful to get periodic reports on open bugs. You can add
+a cron job such as the following if you want to get a weekly email
+outlining all the open bugs against your packages:
+<example>
+# ask for weekly reports of bugs in my packages
+&cron-bug-report;
+</example>
+Replace <var>address</var> with you official Debian
+maintainer address.
+
+ <sect id="submit-bug">Submitting Bugs
+ <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
+<url id="&url-bts-control;" name="BTS instructions"> can tell you how
+to do this.
+ <p>
+We encourage you to file bugs when there are problems. Try to submit
+the bug from a normal user account at which you are likely to receive
+mail. Do not submit bugs as root.
+ <p>
+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 should
+not actually close the bug (unless you secure permission from the
+maintainer).
+
+ <sect>Responding to Bugs
<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/.
+Make sure that any discussions you have about bugs are sent both to
+the original submitter of the bug, and the bug itself (e.g.,
+<email>123@bugs.debian.org</email>).
<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.
+You should <em>never</em> close bugs via the bug server `close'
+command sent to &email-bts-control;. If you do so, the original
+submitter will not receive any feedback on why the bug was closed.
+
+ <sect id="upload-bugfix">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>
+If you are using a new version of <package>dpkg-dev</package> and you do
+your changelog entry properly, the archive maintenance software will close
+the bugs automatically. All you have to do is follow a certain syntax in
+your <file>debian/changelog</file> file:
+<example>
+acme-cannon (3.1415) unstable; urgency=low
+
+ * Frobbed with options (closes: Bug#98339)
+ * Added safety to prevent operator dismemberment, closes: bug#98765,
+ bug#98713, #98714.
+ * Added manpage. Closes: #98725.
+</example>
+
+Technically speaking, the following Perl regular expression is what is
+used:
+<example>
+ /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
+</example>
+
+The author prefers the <tt>(closes: Bug#<var>XXX</var>)</tt> syntax,
+since it stands out from the rest of the changelog entries.
<p>
+If you want to close bugs the old fashioned, manual way, it is usually
+sufficient to mail the <tt>.changes</tt> file to
+<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your
+bug number.
+
+
+ <sect id="lintian-reports">Lintian reports
+ <p>
+You should periodically get the new <package>lintian</package> from
+`unstable' and check over all your packages. Alternatively you can
+check for your maintainer email address at the <url id="&url-lintian;"
+name="online lintian report">. That report, which is updated
+automatically, contains <prgn>lintian</prgn> reports against the
+latest version of the distribution (usually from 'unstable') using the
+latest <package>lintian</package>.
- <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>
+Reporting a great number of bugs for the same problem on a great
+number of different packages &mdash i.e., more than 10 &mdash is a deprecated
+practice. Take all possible steps to avoid submitting bulk bugs at
+all. For instance, if checking for the problem can be automated, add
+a new check to <package>lintian</package> so that an error or warning
+is emitted.
+ <p>
+If you report more than 10 bugs on the same topic at once, it is
+recommended that you send a message to &email-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 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</email> so
+that the bug report is not forwarded to the bug distribution mailing
+list.
+
+
+ <chapt id="newmaint">
+ <heading>Interaction with Prospective Developers</heading>
+
+ <p>
+This chapter describes procedures that existing Debian developers should
+follow when it comes to dealing with wannabe developers.
+
+ <sect id="sponsoring">Sponsoring packages
+ <p>
+Sponsoring a package means uploading a package for a maintainer who is not
+able to do it on their own, a new maintainer applicant. Sponsoring a package
+also means accepting responsibility for it.
+ <p>
+New maintainers usually have certain difficulties creating Debian packages
+— this is quite understandable. That is why the sponsor is there, to check
+the package and verify that it is good enough for inclusion in Debian.
+(Note that if the sponsored package is new, the FTP admins will also have to
+inspect it before letting it in.)
+ <p>
+Sponsoring merely by signing the upload or just recompiling is
+<strong>definitely not recommended</strong>. You need to build the source
+package just like you would build a package of your own. Remember that it
+doesn't matter that you left the prospective developer's name both in the
+changelog and the control file, the upload can still be traced to you.
+ <p>
+If you are an application manager for a prospective developer, you can also
+be their sponsor. That way you can also verify the how the applicant is
+handling the `Tasks and Skills' part of their application.
+
+ <sect>Advocating new developers
+ <p>
+See the page about <url id="&url-newmaint-advocate;"
+name="advocating a prospective developer"> at the Debian web site.
+
+ <sect>Handling new maintainer applications
+ <p>
+Please see <url id="&url-newmaint-amchecklist;" name="Checklist for
+Application Managers"> at the Debian web site.
+
+
+
+ <chapt id="tools">Overview of Debian Maintainer Tools
+ <p>
+This section contains a rough overview of the tools available to
+maintainers. The following is by no means complete or definitive, but
+just a guide to some of the more popular tools.
+ <p>
+Debian maintainer tools are meant to help convenience developers and
+free their time for critical tasks. As Larry Wall says, there's more
+than one way to do it.
+ <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. Further information can be found in
+the package documentation itself. You can also see more info with the
+command <tt>apt-cache show <var>package_name</var></tt>.
+
+
+ <sect id="dpkg-dev">
+ <heading><package>dpkg-dev</package>
+ <p>
+<package>dpkg-dev</package> contains the tools (including
+<prgn>dpkg-source</prgn>) 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</package>
+ <p>
+<package>Lintian</package> 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</package> has already been discussed in <ref
+id="upload-checking"> and <ref id="lintian-reports">.
+
+
+ <sect id="debconf">
+ <heading><package>debconf</package></heading>
+ <p>
+<package>debconf</package> provides a consistent interface to
+configuring packages interactively. It is user interface
+independant, allowing end-users to configure packages with a
+text-only interface, an HTML interface, or a dialog interface. New
+interfaces can be added modularly.
+ <p>
+You can find documentation for this package in the
+<package>debconf-doc</package> package.
+ <p>
+Many feel that this system should be used for all packages requiring
+interactive configuration. <package>debconf</package> is not
+currently required by Debian Policy, however, that may change in the
+future.
+ <p>
+
+
+ <sect id="debhelper">
+ <heading><package>debhelper</package>
+ <p>
+<package>debhelper</package> is a collection of programs that can be
+used in <file>debian/rules</file> 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 some approaches, <package>debhelper</package> is broken into
+several small, granular commands which act in a consistent manner. As
+such, it allows a greater granularity of control than some of the
+other "debian/rules tools".
+ <p>
+There are a number of little <package>debhelper</package> add-on
+packages, too transient to document. You can see the list of most of
+them by doing <tt>apt-cache search ^dh-</tt>.
+
+
+ <sect id="debmake">
+ <heading><package>debmake</package>
+ <p>
+<package>debmake</package>, a pre-cursor to
+<package>debhelper</package>, is a less granular
+<file>debian/rules</file> 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</package>.
+ <p>
+The consensus is that <package>debmake</package> is now deprecated in
+favor of <package>debhelper</package>. However, it's not a bug to use
+<package>debmake</package>.
+
+
+ <sect id="yada">
+ <heading><package>yada</package>
+ <p>
+<package>yada</package> is another packaging helper tool. It uses a
+<file>debian/packages</file> file to auto-generate
+<file>debian/rules</file> and other necessary files in the
+<file>debian/</file> subdirectory.
+ <p>
+Note that <package>yada</package> is called "essentially unmaintained"
+by it's own maintainer, Charles Briscoe-Smith. As such, it can be
+considered deprecated.
+
+
+ <sect id="equivs">
+ <heading><package>equivs</package>
+ <p>
+<package>equivs</package> is another package for making packages. It
+is often suggested for local use if you need to make a package simply
+to fulfill dependencies. It is also sometimes used when making
+``meta-packages'', which are packages whose only purpose is to depend
+on other packages.
+
+
+ <sect id="cvs-buildpackage">
+ <heading><package>cvs-buildpackage</package>
+ <p>
+<package>cvs-buildpackage</package> 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>, <em>unstable</em>, and possibly
+<em>experimental</em> distributions, along with the other benefits of
+a version control system.
+
+
+ <sect id="dupload">
+ <heading><package>dupload</package>
+ <p>
+<package>dupload</package> 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.
+
+
+ <sect id="dput">
+ <heading><package>dput</package>
+ <p>
+The <package>dput</package> package and script does much the same
+thing as <package>dupload</package>, but in a different way. It has
+some features over <package>dupload</package>, such as the ability to
+check the GnuPG signature and checksums before uploading, and the
+possibility of running <tt>dinstall</tt> in dry-run mode after the
+upload.
+
+
+ <sect id="fakeroot">
+ <heading><package>fakeroot</package>
+ <p>
+<package>fakeroot</package> simulates root privileges. This enables
+you to build packages without being root (packages usually want to
+install files with root ownership). If you have
+<package>fakeroot</package> installed, you can build packages as a
+user: <tt>dpkg-buildpackage -rfakeroot</tt>.
+
+
+ <sect id="debootstrap">
+ <heading><package>debootstrap</package>
+ <p>
+The <package>debootstrap</package> package and script allows you to
+"bootstrap" a Debian base system into any part of your filesystem.
+By "base system", we mean the bare minimum of packages required to
+operate and install the rest of the system.
+ <p>
+Having a system like this can be useful in many ways. For instance,
+you can <prgn>chroot</prgn> into it if you want to test your build
+depends. Or, you can test how your package behaves when installed
+into a bare base system.
+
+
+ <sect id="devscripts">
+ <heading><package>devscripts</package>
+ <p>
+<package>devscripts</package> is a package containing a few wrappers
+and tools which you may find helpful for maintaining your Debian
+packages. Example scripts include <prgn>debchange</prgn> and
+<prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>
+file from the command-line, and <prgn>debuild</prgn>, which is a
+wrapper around <prgn>dpkg-buildpackage</prgn>.
+
+
+
+ <sect id="dpkg-dev-el">
+ <heading><package>dpkg-dev-el</package>
+ <p>
+<package>dpkg-dev-el</package> is an Emacs lisp package which provides
+assistance when editing some of the files in the <file>debian</file>
+directory of your package. For instance, when editing
+<file>debian/changelog</file>, there are handy functions for
+finalizing a version and listing the package's current bugs.
+
+
+ <sect id="debget">
+ <heading><package>debget</package>
+ <p>
+<package>debget</package> is a package containing a convenient script
+which can be helpful in downloading files from the Debian archive.
+You can use it to download source packages, for instance (although
+<tt>apt-get source <var>package</var></tt> does pretty much the same
+thing).
+
+
+<!-- FIXME: add the following
+ dpkg-awk
+ alien
+ dpkg-repack
+ grep-dctrl
+ pbuilder -->
+
+
+ </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-declaration:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->