-<!doctype debiandoc system [
-<!-- include version information so we don't have to hard code it
- within the document
- -->
-<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+<!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;
+ <!entity number-of-pkgs "2250">
+ <!entity number-of-maintainers "400">
]>
-
-<!--
- 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.
- -->
-
+<debiandoc>
<!--
-
- 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>
-
-<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 &version;, &date;
+ <book>
-<copyright>Copyright ©1997,1998 Christian Schwarz.
-<p>
+ <title>Debian Developer's Reference
+ <author>Adam Di Carlo, current maintainer <email/aph@debian.org/
+ <author>Christian Schwarz <email/schwarz@debian.org/
+ <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
+ <version>ver. &version;, &date;
+ <copyright>
+ <copyrightsummary>
+copyright ©1998, 1999 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
-<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>
+<file>/usr/doc/copyright/GPL</file> in the Debian GNU/Linux distribution
+or on the World Wide Web at <url
+id="http://www.gnu.org/copyleft/gpl.html" name="the GNU website">.
+You can also obtain it by writing to the Free Software Foundation,
+Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+ <toc detail="sect2">
+
+ <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-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;
+that information is discussed in the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual">. Nor does this reference detail the
+standards to which Debian software must comply; that information can
+be found in the <url id="http://www.debian.org/doc/debian-policy/"
+name="Debian Policy Manual">.
+ <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.
- <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.
+So, you've read all the documentation, you understand what everything
+in the <package/hello/ example package is for, and you're about to
+Debianize your favourite piece of software. How do you actually
+become a Debian developer so that your work can be incorporated into
+the Project?
+ <p>
+Firstly, subscribe to <email/debian-devel@lists.debian.org/ if you
+haven't already. Send the word <tt/subscribe/ in the <em/Subject/ of
+an email to <email/debian-devel-REQUEST@lists.debian.org/. In case of
+problems, contact the list administrator at
+<email/listmaster@lists.debian.org/. More information on available
+mailing lists can be found in <ref id="mailing-lists">.
+ <p>
+You should subscribe and lurk for a bit before doing any coding, and
+you should post about your intentions to work on something to avoid
+duplicated effort.
+ <p>
+Another good list to subscribe to is
+<email/debian-mentors@lists.debian.org/. See <ref id="mentors"> for
+details. The IRC channel <tt/#debian/ on the Linux People IRC network
+(i.e., <tt/irc.debian.org/) can also be helpful.
+
+
+ <sect id="registering">Registering as a Debian developer
+ <p>
+Before you decide to register with the Debian Project, you will need
+to read the <url id="http://www.debian.org/social_contract"
+name="Debian Social Contract">. Registering as a developer means that
+you agree with and pledge to uphold the Debian Social Contract; it is
+very important that maintainers are in accord with the essential ideas
+behind Debian GNU/Linux. Reading the <url
+id="http://www.gnu.org/gnu/manifesto.html" name="GNU Manifesto"> would
+also be a good idea.
+ <p>
+The process of registering as a developer is a process of verifying
+your identity and intentions. As the number of people working on
+Debian GNU/Linux has grown to over &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
+letting them upload packages.
+ <p>
+Registration requires that the following information be sent to
+<email/new-maintainer@debian.org/ as part of the registration
+application:
+<list>
+ <item>
+Your name.
+ <item>
+Your preferred login name on <tt/master/ (seven characters or
+less<footnote>It is not clear to the author why logins on
+<tt>master</tt> cannot be eight characters or greater. If anyone can
+clarify why, I would appreciate it.</footnote>), as well as the email
+address at which you'd prefer to be subscribed to
+<email/debian-private@lists.debian.org/ (typically this will be either
+your primary mail address or your new <tt>debian.org</tt> address).
+ <item>
+A phone number where we can call you. Remember that the new
+maintainer team usually calls during evening hours to save on long
+distance tolls. Please do not give a work number, unless you are
+generally there in the evening.
+ <item>
+A statement of intention, that is, what package(s) you intend to work
+on, which Debian port you will be assisting, or how you intend to
+contribute to Debian.
+ <item>
+A statement that you have read and agree to uphold the <url
+id="http://www.debian.org/social_contract" name="Debian Social
+Contract">.
+ <item>
+Some mechanism by which we can verify your real-life identity. For
+example, any of the following mechanisms would suffice:
+<list>
+ <item>
+A PGP key signed by any well-known signature, such as:
+<list>
+ <item>
+Any current Debian developer you have met <em/in real life/.
+ <item>
+Any formal certification service (such as Verisign, etc.) that
+verifies your identity. A certification that verifies your email
+address, and not you identity, is not sufficient.
+ </list>
+ <item>
+Alternatively, you may identify yourself with a scanned (or physically
+mailed) copy of any formal documents certifying your identity (such as
+a birth certificate, national ID card, U.S. Driver's License, etc.).
+If emailed, please sign the mail with your PGP key.
+ </list>
</list>
-
- 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>
+If you do not have a PGP key yet, generate one. Every developer needs
+a PGP key in order to sign and verify package uploads. You should read
+the PGP manual, since it has much important information which is
+critical to its security. Many more security failures are due to
+human error than to software failure or high-powered spy techniques.
+ <p>
+Our standard is to use <prgn>pgp</prgn> version 2.x. You can use
+<prgn/pgp/ version 5, if and only if you make an RSA key. Note that
+we are also working with the <prgn/gpg/ team so that we can have a
+free alternative to PGP; however, this may take a little bit of time.
+ <p>
+Your PGP key must be at least 1024 bits long. There is no reason to
+use a smaller key, and doing so would be much less secure. Your key
+must be signed with at least your own user ID. This prevents user ID
+tampering. You can do it by executing <tt>pgp -ks
+<var>your_userid</var></tt>.
+ <p>
+If your PGP key isn't on public key servers such as
+<tt>pgp5.ai.mit.edu</tt>, please read the documentation available
+locally <tt>/usr/doc/pgp/keyserv.doc</tt>. That document contains
+instructions on how to put your key on the public key servers. The
+New Maintainer Group will put your public key on the servers if it
+isn't already there.
+ <p>
+Due to export restrictions by the United States government some Debian
+packages, including PGP, have been moved to an ftp site outside of the
+United States. You can find the current locations of those packages on
+<ftpsite/ftp.debian.org/ or <ftpsite/ftp.us.debian.org/ in the
+<ftppath>/pub/debian/README.non-US</ftppath> file.
+ <p>
+Some countries restrict the use of cryptographic software by their
+citizens. This need not impede one's activities as a Debian package
+maintainer however, as it may be perfectly legal to use cryptographic
+products for authentication, rather than encryption purposes (as is
+the case in France). The Debian Project does not require the use of
+cryptography <em/qua/ cryptography in any manner. If you live in a
+country where use of cryptography even for authentication is forbidden
+then please contact us so we can make special arrangements.
+ <p>
+Once you have all your information ready, and your public key is
+available on public key servers, send a message to
+<email/new-maintainer@debian.org/ to register as an offical Debian
+developer so that you will be able to upload your packages. This
+message must contain all the information discussed above. The message
+must also contain your PGP or RSA public key (extracted using <tt>pgp
+-kxa</tt> in the case of PGP) for the database of keys which is
+distributed from <ftpsite/ftp.debian.org/ in
+<ftppath>/pub/debian/doc/debian-keyring.tar.gz</ftppath>, or the
+<package/debian-keyring/ package. Please be sure to sign your request
+message with your chosen public key.
+ <p>
+Once this information is received and processed, you should be
+contacted with information about your new Debian maintainer account.
+If you don't hear anything within 7-14 days, please send a followup
+message asking if your original application was received. Do <em/not/
+re-send your original application, that will just confuse the
+new-maintainer team. Please be patient, especially near release
+points; mistakes do occasionally happen, and people do sometimes run
+out of volunteer time.
- <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).
+
+ <sect id="mentors">Debian Mentors
<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.
+A mailing list called <email/debian-mentors@lists.debian.org/ which
+has been set up for novice maintainers who seek help with initial
+packaging and other developer-related issues. Every new developer is
+invited to subscribe to that list (see <ref id="mailing-lists"> for
+details).
<p>
-
-
- <chapt>Internet Servers<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.
- <sect id="mailing-lists">Mailing lists<p>
- The mailing list server is at <tt/lists.debian.org/. Mail
- <tt/debian-<var/foo/-REQUEST@lists.debian.org/, where
- <tt/debian-<var/foo// is the name of the list, with the word
- <tt/subscribe/ in the Subject to subscribe or
- <tt/unsubscribe/ to unsubscribe.
- <p>
- When replying to messages on the mailing list, please do not
- send a carbon copy (<tt/CC/--this does not mean `courtesy
- copy') to the original poster. Anyone who posts to a
- mailing list should read it to see the responses.
- <p>
- In addition, all messages should usually only be sent to one
- of the following mailing lists: <tt/debian-devel/,
- <tt/debian-policy/, <tt/debian-user/, <tt/debian-announce/,
- <tt/debian-devel-announce/.
+ <chapt id="user-maint">Maintaining Your Debian Information
+
+ <sect id="key-maint">Maintaining Your Public Key
<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.
+Be very careful with your private keys. Do not place them on any
+public servers. Back them up. Read the documentation that comes with
+your software (either PGP or GNUPG); read the FAQs too, for good
+measure.
<p>
-
- <sect>The master server
+If you add or remove signatures from your public key, or add or remove
+user identities, you need to update the key servers and mail your
+public key to <email>keyring-maint@debian.org</email>.
+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>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@lists.debian.org</email>.
+ <item>
+Notify the Debian key ring maintainers that you are leaving by emailing
+to <email>keyring-maint@debian.org</email>.
+ </enumlist>
- <sect>The FTP servers
- <p>
- <sect>The WWW servers
+ <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.debian.org/. Mail
+<tt/debian-<var/foo/-REQUEST@lists.debian.org/, where
+<tt/debian-<var/foo// is the name of the list, with the word
+<tt/subscribe/ in the <em/Subject/ to subscribe to the list or
+<tt/unsubscribe/ to unsubscribe. More detailed instructions on how to
+subscribe and unsubscribe to the mailing lists can be found at <url
+id="http://www.debian.org/MailingLists/subscribe">, <url
+id="ftp://ftp.debian.org/debian/doc/mailing-lists.txt"> or locally in
+<file>/usr/doc/debian/mailing-lists.txt</file> 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/) 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>
+In addition, all messages should usually only be sent to one of the
+following mailing lists: <email/debian-devel@lists.debian.org/,
+<email/debian-policy@lists.debian.org/,
+<email/debian-user@lists.debian.org/,
+<email/debian-announce@lists.debian.org/, or
+<email/debian-devel-announce@lists.debian.org/. Additional mailing
+lists are available for special purposes; see <url
+id="http://www.debian.org/MailingLists/subscribe">. Cross-posting
+(sending the same message to multiple lists) is discouraged.
+ <p>
+<email/debian-private@lists.debian.org/ is a special mailing lists for
+private discussions amongst Debian developers. It is meant to be used
+for posts which for whatever reason should not be published
+publically. As such, it is a low volume list, and users are urged not
+to use <email/debian-private@lists.debian.org/ unless it is really
+necessary. Moreover, do <em/not/ forward email from that list to
+anyone.
+ <p>
+As ever on the net, please trim down the quoting of articles you're
+replying to. In general, please adhere to the usual conventions for
+posting messages.
+ <p>
+Online archives of mailing lists are available at <url
+id="http://www.debian.org/Lists-Archives/">.
+
+ <sect 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 Debian server, and you
+think that the system operators need to be notified of this problem,
+please find the contact address for the particular role at <url
+id="http://www.debian.org/devel/maintainer_contacts">. 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>
+The master server, <tt/master.debian.org/, holds the canonical copy
+of the Debian archive (excluding the non-U.S. packages). Generally,
+package uploads go to this server; see <ref id="upload">.
+ <p>
+<tt/master.debian.org/ is the canonical location for the Bug Tracking
+System (BTS). If you plan on doing some statistical analysis or
+processing of Debian bugs, this would be the place to do it. Please
+describe your plans on <email/debian-devel@lists.debian.org/ before
+implementing anything, however, to reduce unnecessary duplication of
+effort or wasted processing time.
+ <p>
+All Debian developers have accounts on <tt/master.debian.org/. Please
+take care to protect your password to this machine. Try to avoid
+login or upload methods which send passwords over the Internet in the
+clear.
+ <p>
+If you find a problem with <tt/master.debian.org/ such as disk full,
+suspicious activity, or whatever, send an email to
+<email>debian-admin@debian.org</email>. 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@debian.org</email>, but also see the procedures in
+<ref id="archive-manip">.
+
+ <sect1 id="servers-www">The WWW servers
+ <p>
+The main web server, <tt/www.debian.org/, is also known as
+<tt/va.debian.org/. All developers are given accounts on this
+machine.
+ <p>
+If you have some Debian-specific information which you want to serve
+up on the web, you can do do this by putting material in the
+<file>public_html</file> directory under your home directory. You can do
+this on either <tt/va.debian.org/ or <tt/master.debian.org/. Any
+material you put in those areas are accessible via the URLs
+<tt>http://www.debian.org/~<var>user-id</var>/</tt> and
+<tt>http://master.debian.org/~<var>user-id</var>/</tt>, respectively.
+Generally, you'll want to use <tt/va/, for the <tt/www.debian.org/
+address, although in some cases you may need to put it on <tt/master/.
+Please do not put any material on Debian servers not relating to
+Debian, unless you have prior permission. Send mail to
+<email/debian-devel@lists.debian.org/ 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://www.debian.org/Bugs/db/pa/lwww.debian.org.html" name="Bug
+Tracking System">.
+
+
+ <sect1 id="servers-cvs">The CVS server
<p>
+<tt/cvs.debian.org/ is also known as <tt/va.debian.org/, discussed
+above. If you need the use of a publically accessible CVS server, for
+instance, to help coordinate work on a package between many different
+developers, you can request a CVS area on the server.
+ <p>
+Generally, <tt/cvs.debian.org/ offers a combination of local CVS
+access, anonymous client-server read-only access, and full
+client-server access through <prgn>ssh</prgn>. Also, the CVS area can
+be accessed read-only via the Web at <url
+id="http://cvs.debian.org/cgi-bin/cvsweb">.
+ <p>
+To request a CVS area, send a request via email to
+<email>debian-admin@debian.org</email>. Include the name of the
+requested CVS area, what <tt>va.debian.org</tt> user account should
+own the CVSROOT, and why you need it.
+
+
+ <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="http://www.debian.org/distrib/ftplist">. More information
+concerning Debian mirrors can be found at <url
+id="http://www.debian.org/mirror">. This useful page includes
+information and tools which can be helpful if you are interested in
+setting up your own mirror, either for internal or public access.
+ <p>
+Note that mirrors are generally run by third-parties who are
+interested in helping Debian. As such, developers generally do not
+have accounts on these machines.
+ <p>
+Please do not mirror off of <tt/master.debian.org/. This host already
+has too much load. Check the sites above for information, or email
+<email/debian-devel@lists.debian.org/.
+
+
+ <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">, the
+following machines are, or may be made, available to you. If an email
+address is listed, generally that person is the party to contact about
+issues on the machine. Otherwise, the machine is probably managed by
+<email>debian-admin@debian.org</email>.
+
+<taglist>
+ <tag><tt>faure.debian.org</tt></tag>
+ <item>
+An Alpha; if you have an account on <tt>master</tt>, you probably
+already have an account here.
+
+ <tag><tt>kubrick.debian.org</tt></tag>
+ <item>
+A SPARC; if you have an account on <tt>master</tt>, you probably
+already have an account here.
+
+ <tag><tt>pandora.debian.org</tt></tag>
+ <item>
+An i386; if you have an account on <tt>master</tt>, you probably
+already have an account here.
+
+ <tag><tt>albert.debian.org</tt></tag>
+ <item>
+An Alpha; you probably want to use <tt>faure</tt> instead, but you may
+request an account from <email>debian-admin@debian.org</email>.
+
+ <tag><tt>powerpc.debian.org</tt></tag>
+ <item>
+A PowerPC; also known as <tt>tervola.infodrom.north.de</tt>. You may
+request an account from <email>joey@debian.org</email> or
+<email>koptein@debian.org</email>.
+
+ <tag><tt>m68k.debian.org</tt></tag>
+ <item>
+A Motorola 6800x0 machine; you may request an account from
+<email>joey@debian.org</email> or <email>james@nocrew.org</email>.
+Runs an autobuilder.
+
+ <tag><tt>alpha.debian.nl</tt></tag>
+ <item>
+An Alpha; you may request an account from
+<email>debian@cistron.nl</email>.
+
+ <tag><tt>xia0[123].kachinatech.com</tt></tag>
+ <item>
+SPARC and UltraSPARC machines. <tt>xia0[12]</tt> are used for
+automatic compilation; you can request an account on xia03 (an
+UltraSPARC) from <email>wdeng@kachinatech.com</email>.
+
+ </taglist>
+
+
+
+ <chapt id="archive">The Debian Archive
- <chapt>The Debian Archive<p>
-
<sect>Overview
<p>
+The Debian GNU/Linux distribution consists of a lot of Debian packages
+(<tt/.deb/'s, currently around &number-of-pkgs;) and a few additional files
+(documentation, installation disk images, etc.).
+ <p>
+Here is an example directory tree of a complete Debian distribution:
+ <p>
+<example>
+main/
+main/binary-all/
+main/binary-all/admin/
+main/binary-all/base/
+main/binary-all/comm/
+main/binary-all/devel/
+ ...
+main/binary-i386/
+main/binary-i386/admin/
+main/binary-i386/base/
+ ...
+main/binary-m68k
+main/binary-m68k/admin/
+main/binary-m68k/base/
+ ...
+main/source/
+main/source/admin/
+main/source/base/
+ ...
+main/disks-i386/
+main/disks-m68k/
+ ...
+
+contrib/
+contrib/binary-all/
+contrib/binary-i386/
+contrib/binary-m68k/
+ ...
+contrib/source/
+
+non-free/
+non-free/binary-all/
+non-free/binary-i386/
+non-free/binary-m68k/
+ ...
+non-free/source/
+</example>
+ <p>
+As you can see, the top-level directory of the distribution contains
+three directories, namely <em/main/, <em/contrib/, and
+<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
+(<tt/binary-i386/, <tt/binary-m68k/, etc.), and a directory for
+architecture independent packages (<tt/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
+(<tt/disks-i386/, <tt/disks-m68k/, etc.).
+ <p>
+The <em/binary/ and <em/source/ directories are divided further into
+<em/subsections/.
+
- The Debian GNU/Linux distribution consists of a lot of
- Debian packages (<tt/.deb/'s, currently more than 1000) and
- a few additional files (documentation, installation disk
- images, etc.).
- <p>
- Here is an example directory tree of a complete Debian
- distribution:
- <example>
- main/
- main/binary-all/
- main/binary-all/admin/
- main/binary-all/base/
- main/binary-all/comm/
- main/binary-all/devel/
- ...
- main/binary-i386/
- main/binary-m86k/
- ...
- main/source/
- main/disks-i386/
- main/disks-m68k/
- ...
-
- contrib/
- contrib/binary-all/
- contrib/binary-i386/
- contrib/binary-m86k/
- ...
- contrib/source/
-
- non-free/
- non-free/binary-all/
- non-free/binary-i386/
- non-free/binary-m86k/
- ...
- non-free/source/
- </example>
- <p>
- As you can see, the top-level directory of the distribution
- contains three directories, namely <em>main</>,
- <em>contrib</>, and <em>non-free</>. These directories are
- called <em>sections</>.
- <p>
- In each section, there is a directory with the source
- packages (source), a directory for each supported
- architecture (binary-i386, binary-m86k, etc.), and a
- directory for architecture independent packages
- (binary-all).
- <p>
- The <em/main/ section contains additional directories which
- holds the disk images and some essential pieces of
- documentation required for installing the Debian
- distribution on a specific architecture (disks-i386,
- disks-m68k, etc.).
- <p>
- The <em/binary/ and <em/source/ directories are divided
- further into <em/sub-sections/.
- <p>
-
<sect>Sections
<p>
+The <em>main</em> section is what makes up the <em>official Debian
+GNU/Linux distribution</em>. The <em/main/ section is official because
+it fully complies with all our guidelines. The other two sections do
+not, to different degrees; as such, they are not officially part of
+Debian.
+ <p>
+Every package in the main section must fully comply with the <!-- work
+around quoting of fragment idendifiers bug <url
+id="http://www.debian.org/social_contract#guidelines" name="Debian
+Free Software Guidelines"> --> <url
+id="http://www.debian.org/social_contract" name="Debian Free Software
+Guidelines"> (DFSG) and with all other policy requirements as
+described in the <url id="http://www.debian.org/doc/debian-policy/"
+name="Debian Policy Manual">. The DFSG is our definition of ``free
+software.'' Check out the Debian Policy Manual for details.
+ <p>
+The packages which do not apply to the DFSG are placed in the
+<em/non-free/ section. These packages are not considered as part of
+the Debian distribution, though we support their use, and we provide
+infrastructure (such as our bug-tracking system and mailing lists) for
+non-free software packages.
+ <p>
+Packages in the <em/contrib/ section have to comply with the DFSG, but
+may fail other requirements. For instance, they may depend on
+non-free packages.
+ <p>
+The <url id="http://www.debian.org/doc/debian-policy/" name="Debian
+Policy Manual"> contains a more exact definition of the three
+sections. The above discussion is just an introduction.
+ <p>
+The separation of the three sections at the top-level of the archive
+is important for all people who want to distribute Debian, either via
+FTP servers on the Internet or on CD-ROMs: by distributing only the
+<em/main/ and <em/contrib/ sections, one can avoid any legal risks.
+Some packages in the <em/non-free/ section do not allow commercial
+distribution, for example.
+ <p>
+On the other hand, a CD-ROM vendor could easily check the individual
+package licenses of the packages in <em/non-free/ and include as many
+on the CD-ROMs as he's allowed. (Since this varies greatly from vendor
+to vendor, this job can't be done by the Debian developers.)
- The <em>main section</> is what makes up the <em>Debian
- GNU/Linux distribution</>. This is because the packages in
- the other two sections do not fully comply with all our
- guidelines.
- <p>
- For example, every package in the main distribution must
- fully comply with the <em>Debian Free Software Guidelines</>
- (DFSG) and with all other policy requirements as described
- in the <em>Debian Policy Manual</em>. (The DFSG is our
- definition of ``free software.'' Check out the Debian Policy
- Manual for details.)
- <p>
- The packages which do not apply to the DFSG are placed in
- the <em>non-free</> section. These packages are not
- considered as part of the Debian distribution, though we
- support their use, and we provide infrastructure (such as
- our bug-tracking system and mailing lists) for non-free
- software packages.
- <p>
- Packages in the <em>contrib</> section have to apply to
- the DFSG, but fail other requirements.
- <p>
- (The Debian Policy Manual contains a more exact definition
- of the three sections. This is just meant to be an
- introduction.)
- <p>
- The separation of the three sections at the top-level of
- the archive is important for all people who want to
- distribute Debian, either via FTP servers on the Internet
- or on CD-ROMs: by distributing only the <em/main/ and
- <em/contrib/ sections, one can avoid any legal risks,
- since some packages in the <em/non-free/ section do not
- allow commercial distribution, for example.
- <p>
- On the other hand, a CD-ROM vendor could easily check the
- individual package licenses of the packages in <em/non-free/
- and include as many on the CD-ROMs as he's allowed. (Since
- this varies from vendor to vendor very much, this job can't
- be done by the Debian developers.)
- <p>
<sect>Architectures
<p>
+In the first days, the Linux kernel was only available for the Intel
+i386 (or greater) platforms, and so was Debian. But when Linux became
+more and more popular, the kernel was ported to other architectures,
+too.
+ <p>
+The Linux 2.0 kernel supports Intel 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.
- 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>
+Debian GNU/Linux 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.
- <sect>Sub sections
- <p>
- The sections <em/main/, <em/contrib/, and <em/non-free/ are
- split into <em/sub sections/, to simplify the installation
- process and the maintainance of the archive.
- <p>
+ <sect>Subsections
+ <p>
+The sections <em/main/, <em/contrib/, and <em/non-free/ are split into
+<em/subsections/ to simplify the installation process and the
+maintainance of the archive. Subsections are not formally defined,
+excepting perhaps the `base' subsection. Subsections exist simply
+to simplify the organization and browsing of available packages.
+Please check the current Debian distribution to see which sections are
+available.
+
<sect>Packages
<p>
+There are two types of Debian packages, namely <em/source/ and
+<em/binary/ packages.
+ <p>
+Source packages consist of either two or three files: a <tt/.dsc/
+file, and either a <tt/.tar.gz/ file or both an <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. If a package is distributed elsewhere
+too, the <tt/.orig.tar.gz/ file stores the so-called <em/upstream
+source code/, that is the source code that's distributed from the
+<em/upstream maintainer/ (often the author of the software). In this
+case, the <tt/.diff.gz/ contains the changes made by the Debian
+maintainer.
+ <p>
+The <tt/.dsc/ lists all the files in the source package together with
+checksums (md5sums) and some additional info about the package
+(maintainer, version, etc.).
- 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, are themselves
+contained within <em/distribution directories/. Every distribution is
+contained in the <tt/dists/ directory in the top-level of the Debian
+archive itself (the symlinks from the top-level directory to the
+distributions themselves are for backwards compatability and are
+deprecated).
+ <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 <ftppath>/pub/debian</ftppath>).
+ <p>
+Within that archive root, the actual distributions are contained in
+the <tt/dists/ directory. Here is an overview of the layout:
+ <p>
+<example>
+<var>archive root</var>/dists/<var>distribution</var>/<var>section</var>/<var>architecture</var>/<var>subsection</var>/<var>packages</var>
+</example>
+
+Extrapolating from this layout, you know that to find the i386 base
+packages for the distribution <em/slink/, you would look in
+<ftppath>/debian/dists/slink/main/binary-i386/base/</ftppath>.
+
+ <sect1>Stable, unstable, and sometimes frozen
+ <p>
+There is always a distribution called <em/stable/ (residing in
+<tt>dists/stable</tt>) and one called <em/unstable/ (residing in
+<tt>dists/unstable</tt>). This reflects the development process of the
+Debian project.
+ <p>
+Active development is done in the <em/unstable/ distribution (that's
+why this distribution is sometimes called the <em/development
+distribution/). Every Debian developer can update his or her packages
+in this distribution at any time. Thus, the contents of this
+distribution change from day-to-day. Since no special effort is done
+to test this distribution, it is sometimes ``unstable.''
+ <p>
+After a period of development, the <em/unstable/ distribution is
+copied in a new distribution directory, called <em/frozen/. When that
+occurs, no changes are allowed to the frozen distribution except bug
+fixes; that's why it's called ``frozen.'' After another month or a
+little longer, the <em/frozen/ distribution is renamed to <em/stable/,
+overriding the old <em/stable/ distribution, which is removed at that
+time.
+ <p>
+This development cycle is based on the assumption that the
+<em/unstable/ distribution becomes <em/stable/ after passing a period
+of testing as <em/frozen/. Even once a distribution is considered
+stable, a few bugs inevitably remain--that's why the stable
+distribution is updated every now and then. However, these updates are
+tested very carefully and have to be introduced into the archive
+individually to reduce the risk of introducing new bugs. You can find
+proposed additions to <em/stable/ in the <tt/proposed-updates/
+directory. Those packages in <tt/proposed-updates/ that pass muster
+are periodically moved as a batch into the stable distribution and the
+revision level of the stable distribution is incremented (e.g., `1.3'
+becomes `1.3r1', `2.0r2' becomes `2.0r3', and so forth).
+ <p>
+Note that development under <em/unstable/ is continued during the
+``freeze'' period, since a new <em/unstable/ distribution is be
+created when the older <em/unstable/ is moved to <em/frozen/.
+Another wrinkle is that when the <em/frozen/ distribution is offically
+released, the old stable distribution is completely removed from the
+Debian archives (although you can still find it from servers which
+serve up older, obsolete distributions).
+ <p>
+In summary, there is always a <em/stable/ and an <em/unstable/
+distribution available, and the <em/frozen/ distribution shows up for
+a month or so from time to time.
+
+
+ <sect1>Experimental
+ <p>
+The <em/experimental/ distribution is a specialty distribution. It is
+not a full distribution in the same sense that `stable' and `unstable'
+are. Instead, it is meant to be a temporary staging area for highly
+experimental software where there's a good chance that the software
+could break your system. Users who download and install packages from
+<em/experimental/ are expected to have been duly warned. In short,
+all bets are off for the <em/experimental/ distribution.
+ <p>
+Developers should be very selective in the use of the
+<em/experimental/ distribution. Even if a package is highly unstable,
+it could well still go into <em/unstable/; just state a few warnings
+in the description. However, if there is a chance that the software
+could do grave damage to a system, it might be better to put it into
+<em/experimental/.
+ <p>
+For instance, an experimental encrypted file system should probably go
+into <em>experimental</em>. A new, beta, version of some software
+which uses completely different configuration might go into
+<em>experimental</em> at the maintainer's discretion. New software
+which isn't likely to damage your system can go into
+<em>unstable</em>. 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>
+However, using <em>experimental</em> as a personal staging area is not
+always the best idea. You can't replace or upgrade the files in there
+on your own (<prgn>dinstall</prgn> and the Debian archive maintainers
+do that). Additionally, you'll have to remember to ask the archive
+maintainers to delete the package one you have uploaded it to
+<em>unstable</em>. Using your personal web space on
+<tt>va.debian.org</tt> is generally a better idea, so that you put
+less strain on the Debian archive maintainers.
+
- 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 id="codenames">Release code names
+ <p>
+Every released Debian distribution has a <em/code name/: Debian 1.1 is
+called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,
+`hamm'; Debian 2.1, `slink'; and Debian 2.2, `potato'. There is
+also a ``pseudo-distribution'', called `sid' which is contains
+packages for architectures which are not yet officially supported or
+released by Debian. These architectures are planned to be integrated
+into the mainstream distribution at some future date.
+ <p>
+Since the Debian has an open development model (i.e., everyone can
+participate and follow the development) even the unstable distribution
+is distributed via the Internet on the Debian FTP and HTTP server
+network. Thus, if we had called the directory which contains the
+development version `unstable', 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 already very
+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 (i.e.,
+`slink'). These names stay the same during the development period
+and after the release; symbolic links, which can be changed, are made
+to indicate the currently released stable distribution. That's why
+the real distribution directories use the <em/code names/ and symbolic
+links for <em/stable/, <em/unstable/, and <em/frozen/ point to the
+appropriate release directories.
+
+
+ <chapt id="upload">Package uploads
<sect>Announcing new packages
<p>
- If you want to create a new package for the Debian
- distribution, you have to send a short email to
- <em/debian-devel/ describing your plans before you upload
- the new package.
- <p>
- This has the following advantages:
-
+If you want to create a new package for the Debian distribution, you
+should first check the <url
+id="http://www.debian.org/doc/prospective-packages.html"
+name="Work-Needing and Prospective Packages (WNPP)"> list. Checking
+the WNPP ensures that no one is already working on packaging that
+software, and that effort is not duplicated. Assuming no one else is
+already working on your prospective package, you must then send a
+short email to <email/debian-devel@lists.debian.org/ describing your
+plan to create a new package. You should set the subject of the email
+to ``intent to package <var/foobar/'', substituting the name of the new
+package for <var/foobar/.
+ <p>
+There are a number of reasons why we ask maintainers to follow these
+steps:
<list compact>
- <item>It helps the (potentially new) maintainer to tap
- into the experience of people on the list, and lets
- them know if any one else is working on it already
- <p>
- <item>It lets other people thinking about working on the
- package know that there already is a volunteer, and
- efforts may be shared
- <p>
- <item>It lets the rest of the maintainers know more about
- the package than the one line description and the
- changelog entry "Initial version" that generally gets
- posted to debian-devel-changes by default
- <p>
- <item>It is helpful to the people who live off unstable
- (and form our first line of testers); we should
- encourage these people
- <p>
- <item>I think the announcements gives us a better feel of
- what is going on, and what is new, in the project.
- <p>
- <item>We should not dismiss anybody who installs from
- unstable and helps us debug our packages as "fools,
- fools, you installed from unstable; you deserve what
- you get"--we derive a certain benefit from the alpha
- testers
- <p>
- <item>If we appreciate alpha testers, than any name
- changes have to be backwards compatible with the
- people who already installed the old package (conflict
- and replace old package name at a minimum)
+ <item>
+It helps the (potentially new) maintainer to tap into the experience
+of people on the list, and lets them know if any one else is working
+on it already.
+ <item>
+It lets other people thinking about working on the package know that
+there already is a volunteer, and efforts may be shared. The ``intent
+to package'' message to <email/debian-devel@lists.debian.org/ will be
+picked up the the WNPP maintainer, and your intention will be
+published in subsequent versions of the WNPP document.
+ <item>
+It lets the rest of the maintainers know more about the package than
+the one line description and the changelog entry ``Initial version''
+that generally gets posted to <tt/debian-devel-changes/ by default.
+ <item>
+It is helpful to the people who live off unstable (and form our first
+line of testers); we should encourage these people.
+ <item>
+The announcements give maintainers and other interested parties a
+better feel of what is going on, and what is new, in the project.
</list>
-
- <sect>Uploading a package
- <p>
+
+
+ <sect id="uploading">Uploading a package
<sect1>Generating the changes file
<p>
-
- When a package is uploaded to the Debian FTP archive, it
- must be accompanied by a <tt/.changes/ file which gives
- directions for its handling. This is usually generated by
- <prgn/dpkg-genchanges/.
+When a package is uploaded to the Debian FTP archive, it must be
+accompanied by a <tt/.changes/ file, which gives directions to the
+archive maintainers for its handling. This is usually generated by
+<prgn/dpkg-genchanges/ during the normal package build process.
<p>
-
- This file is a control file with the following fields:
- <list compact>
+The changes file is a control file with the following fields:
+ <p>
+<list compact>
<item><tt/Format/
<item><tt/Date/
<item><tt/Source/
<item><tt/Files/
</list>
<p>
+All of these fields are mandatory for a Debian upload. See the list
+of control fields in the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual"> for the contents of these fields.
+Only the <tt/Distribution/ field is discussed here, since it relates
+to the archive maintenance policies.
- 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-dist">Picking a distribution
+ <p>
+Notably, the <tt/Distribution/ field, which originates from the
+<file>debian/changelog</file> file, indicates which distribution the
+package is intended for. There are four possible values for this
+field: `stable', `unstable', `frozen', or `experimental'; these values
+can also be combined. For instance, if you have a crucial security
+fix release of a package, and the package has not diverged between the
+<em/stable/ and <em/unstable/ distributions, then you might put
+`stable unstable' in the <file>changelog</file>'s <tt/Distribution/ field.
+Or, if Debian has been frozen, and you want to get a bug-fix release
+into <em/frozen/, you would set the distribution to `frozen unstable'.
+(See <ref id="upload-frozen"> for more information on when to upload to
+<em/frozen/.) Note that setting the distribution to `stable' 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/. Also note that it never makes sense
+to combine the <em/experimental/ distribution with anything else.
<p>
+The first time a version is uploaded which corresponds to a particular
+upstream version the original source tar file should be uploaded and
+included in the <tt/.changes/ file; subsequent times the very same tar
+file should be used to build the new diffs and <tt/.dsc/ files, and it
+need not then be uploaded.
+ <p>
+By default <prgn/dpkg-genchanges/ and <prgn/dpkg-buildpackage/ will
+include the original source tar file if and only if the Debian
+revision part of the source version number is <tt/0/ or <tt/1/,
+indicating a new upstream version. This behaviour may be modified by
+using <tt/-sa/ to always include it or <tt/-sd/ to always leave it
+out.
+ <p>
+If no original source is included in the upload then the original
+source tar-file used by <prgn/dpkg-source/ when constructing the
+<tt/.dsc/ file and diff to be uploaded <em/must/ be byte-for-byte
+identical with the one already in the archive. If there is some
+reason why this is not the case then the new version of the original
+source should be uploaded, possibly by using the <tt/-sa/ flag.
+
+ <sect2 id="upload-frozen">Uploading to <em/frozen/
+ <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/.
+ <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/ 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/grave/, or
+<em/important/ severity are always allowed for those packages that
+must exist in the final release
+ <item>
+<em/critical/, <em/grave/, and <em/important/ bug fixes are only
+allowed for non-necessary packages if they don't add any new features
+ <item>
+normal 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>
+Remember, 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 and the severity
+of the introduced bug.
+
- 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-checking">Checking the package prior to upload
<p>
+Before you upload your package, you should do basic testing on it.
+Make sure you try the following activities (you'll need to have an
+older version of the Debian package around).
+<list>
+ <item>
+Install the package and make sure the software works, or upgrade the
+package from an older version to your new version if a Debian package
+for it already exists.
+ <item>
+Run <prgn/lintian/ over the package. You can run <prgn/lintian/ as
+follows: <tt>lintian -v <var>package-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/ generates, try adding the
+<tt/-i/ switch, which will cause <prgn/lintian/ to output a very
+verbose description of the problem.
+ <p>
+Normally, a package should <em/not/ be uploaded if it causes lintian
+to emit errors (they will start with <tt/E/).
+ <p>
+For more information on <prgn/lintian/, see <ref id="lintian">.
+ <item>
+Downgrade the package to the previous version (if one exists) -- this
+tests the <tt/postrm/ and <tt/prerm/ scripts.
+ <item>
+Remove the package, then reinstall it.
+ </list>
+
- 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 id="upload-master">Uploading to <tt/master/
<p>
+To upload a package, you need a personal account on
+<ftpsite>master.debian.org</ftpsite>. All maintainers should already
+have this account, see <ref id="servers-master">. You can use either
+<prgn/ssh/ or <prgn/ftp/ to transfer the files. In either case, the
+files need to be placed into
+<ftppath>/home/Debian/ftp/private/project/Incoming</ftppath>. (You
+cannot upload to Incoming on master using anonymous FTP -- you must
+use your user-name and password.)
+ <p>
+<em/Note:/ Do not upload packages containing software that is
+export-controlled by the United States government to <tt/master/, or
+to the overseas upload queues on <tt/chiark/ or <tt/erlangen/. This
+prohibition covers almost all cryptographic software, and even
+sometimes software that contains ``hooks'' to cryptographic software,
+such as electronic mail readers that support PGP encryption and
+authentication. Uploads of such software should go to <tt/non-us/
+(see below). If you are not sure whether U.S. export controls apply
+to your package, post a message to
+<email/debian-devel@lists.debian.org/ and ask.
+ <p>
+You may also find the Debian package <package/dupload/ useful when
+uploading packages. This handy program is distributed with defaults
+for uploading via <prgn/ftp/ to <tt/master/, <tt/chiark/, and
+<tt/erlangen/. It can also be configured to use <prgn/ssh/. See
+<manref name="dupload" section="1"> and <manref name="dupload"
+section="5"> for more information.
+
- 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/chiark/
+ <p>
+If you have a slow network connection to <tt/master/, there are
+alternatives. One is to upload files to <tt/Incoming/ via a
+upload queue in Europe on <tt/chiark/. For details connect
+to <ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP
+and read
+<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
+ <p>
+<em/Note:/ Do not upload packages containing software that is
+export-controlled by the United States government to the queue on
+<tt/chiark/. Since this upload queue goes to <tt/master/, the
+prescription found in <ref id="upload-master"> applies here as well.
<p>
+The program <tt/dupload/ supports uploads to <tt/chiark/; please refer
+to the documentation that comes with the program for details.
- <sect1>Transferring the files to master
+
+ <sect1>Uploads via <tt/erlangen/
+ <p>
+Another upload queue is available in Germany: just upload
+the files via anonymous FTP to <url
+id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">.
+ <p>
+The upload must be a complete Debian upload, as you would put it into
+<tt/master/'s <tt/Incoming/, i.e., a <tt/.changes/ files along with the
+other files mentioned in the <tt/.changes/. The queue daemon also
+checks that the <tt/.changes/ is correctly PGP-signed by a Debian
+developer, so that no bogus files can find their way to <tt/master/
+via the queue. Please also make sure that the <tt/Maintainer/ field
+in the <tt/.changes/ contains <em/your/ e-mail address. The address
+found there is used for all replies, just as on <tt/master/.
<p>
- To upload a package, you need a personal account on the
- master server. Just log in via ftp and transfer the
- files to
- `<tt>/home/Debian/ftp/private/project/Incoming</tt>.'
- (You cannot upload to Incoming on master using anonymous
- FTP--you must use your user-name and password.)
+There's no need to move your files into a second directory after the
+upload as on <tt/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 <tt/master/, but in case of errors you're
+notified, too.
<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.
+<em/Note:/ Do not upload packages containing software that is
+export-controlled by the United States government to the queue on
+<tt/erlangen/. Since this upload queue goes to <tt/master/, the
+prescription found in <ref id="upload-master"> applies here as well.
<p>
+The program <prgn/dupload/ supports uploads to <tt/erlangen/; please refer
+to the documentation that comes with the program for details.
- <sect1>Uploads via Chiark
+
+ <sect1>Uploading to the non-us server
<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>.
+To upload a package to the <em/non-us/ server you just have to
+transfer the files via anonymous ftp to <url
+id="ftp://non-us.debian.org/pub/debian-non-US/Incoming">. Note, that
+the <tt>.changes</tt> file must have a valid PGP signature from one of
+the keys of the developers key-ring.
+
+
+ <sect id="upload-announce">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 <em/Subject/ field, and should contain the PGP-signed
+<tt/.changes/ file. Some additional explanatory text may be added
+before the start of the <tt/.changes/ file.
+ <p>
+If a package is released with the <tt/Distribution:/ set to
+`stable', the announcement is sent to
+<email/debian-changes@lists.debian.org/. If a package is released
+with <tt/Distribution:/ set to `unstable', `experimental', or
+`frozen' (when present), the announcement should be posted to
+<email/debian-devel-changes@lists.debian.org/ instead.
+ <p>
+On occasion, it is necessary to upload a package to both the
+<em/stable/ and <em/unstable/ distributions; this is done by putting
+both distributions in the <tt/Distribution:/ line. In such a case the
+upload announcement should go to both of the above mailing lists.
+ <p>
+The <prgn/dupload/ program is clever enough to determine for itself
+where the announcement should go, and will automatically mail the
+announcement to the right list. See <ref id="dupload">.
+
+ <sect id="upload-notification">Notification that a new package has been installed
+ <p>
+The Debian archive maintainers are responsible for handling package
+uploads. For the most part, uploads are automatically handled on a
+daily basis by an archive maintenance tool called <prgn/dinstall/.
+Specifically, updates to existing packages to the `unstable'
+distribution are handled automatically. In other cases, notably new
+packages, placing the uploaded package into the distribution is
+handled manually. When uploads are handled manually, the change to the
+archive may take up to a week to occur (please be patient).
+ <p>
+In any case, you will receive notification indicating that the package
+has been uploaded via email. Please examine this notification
+carefully. You may notice that the package didn't go into the section
+you thought you set it to go into. Read on for why.
+
+ <sect1 id="override-file">The override file
<p>
- The program <tt/dupload/ support uploads to chiark, please
- refer to the documentation that comes with the program,
- for details.
+The <file>debian/control</file> file's <tt/Section/ and <tt/Priority/
+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/. Sometimes the
+<em/override file/ needs correcting. Simply changing the package's
+<file>control</file> file is not going to work. Instead, you should email
+<email/override-change@debian.org/ or submit a bug against
+<package/ftp.debian.org/.
+ <p>
+For more information about <em/override files/, see
+<manref name="dpkg-scanpackages" section="8"/>,
+<file>/usr/doc/debian/bug-log-mailserver.txt</file>, and
+<file>/usr/doc/debian/bug-maint-info.txt</file>.
+
+
+
+ <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 NMUs, which is explained in the next section.
+
+ <sect id="nmu-terms">Terminology
+ <p>
+There are two new terms used throughout this section: ``binary NMU''
+and ``source NMU''. These terms are used with specific technical
+meaning throughout this document. Both binary 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/ upload.
+ <p>
+A source NMU is a 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.
+ <p>
+A binary NMU is a recompilation and upload of a binary package for a
+new architecture. As such, it is usually part of a porting effort. A
+binary NMU is non-maintainer uploaded binary version of a package
+(often for another architecture), 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 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, 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 I use the unqualified term ``NMU'', I
+mean both source and binary NMUs.
+
+
+ <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 frozen. Porters have
+slightly different rules than non-porters, due to their unique
+circumstances (see <ref id="source-nmu-when-porter">).
+ <p>
+Only critical changes or security bug fixes make it into stable. 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 (i.e., do a source NMU).
+ <p>
+During the release freeze (see <ref id="upload-frozen">), NMUs which
+fix important 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/ be made in a non-maintainer
+upload.
+
- <sect1>Uploads via Erlangen
+ <sect1 id="nmu-version">Source NMU version numbering
<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</>.
+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>
- 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.
+If you are doing a non-maintainer upload (NMU), you should add a new
+minor version number to the <var/debian-revision/ 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>
- There's no need to move your files into a second directory
- after the upload as on chiark. And, in any case, you
- should get some mail reply from the queue daemon what
- happened to your upload. Hopefully it should have been
- moved to master, but in case of errors you're notified,
- too.
+The 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>
- The program <tt/dupload/ support uploads to erlangen,
- please refer to the documentation that comes with the
- program, for details.
+If there is no <var/debian-revision/ 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/ value `0.1'. The
+usual maintainer of a package should start their <var/debian-revision/
+numbering at `1'. Note that if you do this, you'll have to invoke
+<prgn>dpkg-buildpackage</prgn> with the <tt/-sa/ 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>Uploading to the non-us server
+
+ <sect1 id="nmu-changelog">Source NMUs must have a new changelog entry
<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,
+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>
+By convention, source NMU changelog entries start with the line
+<example>
+ * Non-maintainer upload
+</example>
- <item> read the diff and decide on each part of it
- themselves, or
- <item> if the maintainer decides not to apply the patch
- but to release a new version, read the description of the
- changes to the next upstream version and ensure that they
- fix each problem that was fixed in the non-maintainer
- release.
- </list>
- <p>
- In addition, the normal maintainer should <em/always/
- include an entry in the changelog file documenting the
- non-maintainer upload.
- <p>
+ <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/) 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/), 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 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,
+the bugs in the Bug Tracking System which are fixed need to be
+<em/notified/ but not actually <em/closed/ by the non-maintainer.
+Technically, only the official package maintainer or the original bug
+submitter are allowed to close bugs. However, the person making the
+non-maintainer release must send a short message to the relevant bugs
+explaining that the bugs have been
+fixed by the NMU. Using <email/control@bugs.debian.org/, the party
+doing the NMU should also set the severity of the bugs fixed in the
+NMU to `fixed'. This ensures that everyone knows that the bug was
+fixed in an NMU; however the bug is left open until the changes in the
+NMU are incorporated officially into the package by the official
+package maintainer. Also, open a bug with the patches needed to
+fix the problem, or make sure that one of the other (already open) bugs
+has the patches.
+ <p>
+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/ retain the entry
+in the changelog file documenting the non-maintainer upload.
+
- <sect>Maintainer changes
+ <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/ change the value of the maintainer in the
+<file>debian/control</file> file. Your name from 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 which
+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 one <em>i386</em> binary package, there has to be a
+recompile for each architecture, which is around five 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 more 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).
+ <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>
+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="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging 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 your building already being installed (a
+sub-case of the above issue).
+ <item>
+Don't rely on <prgn>egcc</prgn> being available; don't rely on
+<prgn>gcc</prgn> being a certain version.
+ <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 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 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/ is as <tt>dpkg-buildpackage
+-B -m<var/porter-email/</tt>. Of course, set <var/porter-email/ 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="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.
+ <p>
+Again, the situation varies depending on the distribution they are
+uploading to. Crucial fixes (i.e., changes need to get a source
+package to compile for a released-targeted architecture) can be
+uploaded with <em/no/ 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 -- 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 `important' 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>
- 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/.
+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/ 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/, based on
+architecture <var/X/.
+
+
+ <sect1 id="buildd">
+ <heading><package>buildd</package>
+ <p>
+The <package/buildd/ system is used as a distributed, client-server
+build distribution system. It is usually used in conjunction with
+<em/auto-builders/, 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/ 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/sbuild/ and <prgn/wanna-build/.
+ <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>Moving packages
+ <p>
+Sometimes a package will change either its section or its subsection.
+For instance, a package from the `non-free' section might be GPL'd in
+a later version; in this case you should consider moving it to `main'
+or `contrib' (see the <url
+id="http://www.debian.org/doc/debian-policy/" name="Debian Policy
+Manual"> for guidelines).
+ <p>
+In this case, it is sufficient to edit the package control information
+normally and re-upload the package (see the <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual"> for
+details). Carefully examine the installation log sent to you when the
+package is installed into the archive. If for some reason the old
+location of the package remains, file a bug against
+<tt/ftp.debian.org/ asking that the old location be removed. Give
+details on what you did, since it might be a <prgn/dinstall/ bug.
+
+
+ <sect>Removing packages
+ <p>
+If for some reason you want to completely remove a package (say, if it
+is an old compatibility library which is not longer required), you
+need to file a bug against <tt/ftp.debian.org/ asking that the
+package be removed. Make sure you indicate which distribution the
+package should be removed from.
+ <p>
+If in doubt concerning whether a package is disposable, email
+<email/debian-devel@lists.debian.org/ asking for opinions. Also of
+interest is the <prgn/apt-cache/ program from the <package/apt/
+package. When invoked as <tt>apt-cache showpkg
+/var/cache/apt/pkgcache.bin <var/package/</tt>, the program will show
+details for <var/package/, including reverse depends.
+
+ <sect1>Removing packages from <tt/Incoming/
+ <p>
+If you decide to remove a package from <tt/Incoming/, it is nice but
+not required to send a notification of that to the appropriate
+announce list (either <email/debian-changes@lists.debian.org/ or
+<email/debian-devel-changes@lists.debian.org/).
+
+ <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="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual"> for details). Once you've uploaded
+that package, and the package has moved into the archive, file a bug
+against <tt/ftp.debian.org/ asking to remove the package with the
+obsolete name.
+
+
+
+ <sect id="orphaning">Orphaning a package
+ <p>
+If you can no longer maintain a package, then you should set the
+package maintainer to <tt>Debian QA Group
+<debian-qa@lists.debian.org></tt> and email
+<email/wnpp@debian.org/ indicating that the package is now orphaned.
+If the package is especially crucial to Debian, you should instead
+email <email/debian-devel@lists.debian.org/ asking for a new
+maintainer.
+
+
+ <sect id="adopting">Adopting a package
+ <p>
+Periodically, a listing of packages in need of new maintainers will be
+sent to <email/debian-devel@lists.debian.org</email> list. This list
+is also available at in the Work-Needing and Prospective Packages
+document (WNPP), <url
+id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html">
+and at <url id="http://www.debian.org/doc/prospective-packages.html">.
+If you wish to take over maintenance of any of the packages listed in
+the WNPP, or if you can no longer maintain a packages you have, or you
+simply want to know if any one is working on a new package, send a
+message to <email/wnpp@debian.org/.
+ <p>
+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@lists.debian.org/.
+ <p>
+If you take over an old package, you probably want to be listed as the
+package's official maintainer in the bug system. This will happen
+automatically once you upload a new version with an updated
+<tt/Maintainer:/ field, although it can take a couple of weeks. 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
+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="http://www.debian.org/Bugs/" name="Debian bug tracking system
+(BTS)"> for your packages. The BTS contains all the open bugs against
+your packages.
+ <p>
+Maintainers interact with the BTS via email addresses at
+<tt/bugs.debian.org/. Documentation on available commands can be
+found at <url id="http://www.debian.org/Bugs/">, or, if you have
+installed the <package/debian-doc/ package, you can look at the local
+files <file>/usr/doc/debian/bug-*</file>.
+ <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
+0 17 * * fri echo "index maint <var>maintainer-address</var>" | mail request@bugs.debian.org
+</example>
+Replace <var>maintainer-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
+BTS <url id="http://www.debian.org/Bugs/server-control.html"
+name="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 are should
+not actually close the bug (unless you secure permission from the
+maintainer).
+
+ <sect>Responding to Bugs
<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.
+Make sure that any discussions you have about bugs are sent both to
+the original submitter of the bug, and the bug itself (i.e.,
+<email>123@bugs.debian.org</email>).
<p>
+You should <em>never</em> close bugs via the bug server `close'
+command sent to <email>control@bugs.debian.org</email>. If you do so,
+the original submitter will not receive any feedback on why the bug
+was closed.
+
+ <sect>When bugs are closed by new uploads
+ <p>
+If you fix a bug in your packages, it is your responsibility as the
+package maintainer to close the bug when it has been fixed. However,
+you should not close the bug until the package which fixes the bug has
+been accepted into the Debian archive. Therefore, once you get
+notification that your updated package has been installed into the
+archive, you can and should close the bug in the BTS.
+ <p>
+Again, see the BTS documentation for details on how to do this.
+Often, it is sufficient to mail the <tt/.changes file to
+<email/<var/XXX/-done@bugs.debian.org/, where <var/XXX/ is your bug
+number.
+
+
+ <sect id="lintian-reports">Lintian reports
+ <p>
+You should periodically get the new <package/lintian/ from `unstable' and
+check over all your packages. Alternatively you can check for your
+maintainer email address at the <url
+id="http://www.debian.org/lintian/" name="online lintian report">.
+That report, which is updated automatically, contains <prgn/lintian/
+reports against the latest version of the distribution (usually from
+'unstable') using the latest <package/lintian/.
- <chapt>Handling bug reports<p>
<sect>Reporting lots of bugs at once
<p>
- If you report more then 10 bugs on the same topic at once,
- it is recommended that you send a message to debian-devel
- describing your intention before submitting the report. This
- will allow other developers to verify that the bug is a real
- problem. In addition, it will prevent the situation where
- several maintainers start filing the same bug report
- simultaneously.
- <p>
- Note, that when sending lots of bugs on the same subject,
- you should send the bug report to
- <tt/maintonly@bugs.debian.org/ so that the bug report is not
- forwarded to the bug distribution mailing list.
- <p>
-
-</book>
+Reporting a great number of bugs for the same problem on a great
+number of different packages -- i.e., more than 10 -- 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/ 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@lists.debian.org/ describing your intention before
+submitting the report. This will allow other developers to verify that
+the bug is a real problem. In addition, it will help prevent a
+situation in which several maintainers start filing the same bug
+report simultaneously.
+ <p>
+Note that when sending lots of bugs on the same subject, you should
+send the bug report to <email/maintonly@bugs.debian.org/ so that the
+bug report is not forwarded to the bug distribution mailing list.
+
+
+ <chapt id="tools">Overview of Debian Maintainer Tools
+ <p>
+This section contains a rough overview of the tools available to
+maintainers. These tools are meant to help convenience developers and
+free their time for critical tasks.
+ <p>
+Some people prefer to use high-level package maintenance tools and
+some do not. Debian is officially agnostic on this issue; any tool
+which gets the job done is fine. Therefore, this section is not meant
+to stipulate to anyone which tools they should use or how they should
+go about with their duties of maintainership. Nor is it meant to
+endorse any particular tool to the exclusion of a competing tool.
+ <p>
+Most of the descriptions of these packages come from the actual
+package descriptions themselves. Further information can be found in
+the package documentation itself.
+
+
+ <sect id="dpkg-dev">
+ <heading><package/dpkg-dev/
+ <p>
+<package/dpkg-dev/ contains the tools (including
+<prgn/dpkg-source/) required to unpack, build and upload Debian source
+packages. These utilities contain the fundamental, low-level
+functionality required to create and manipulated packages; as such,
+they are required for any Debian maintainer.
+
+
+ <sect id="lintian">
+ <heading><package/lintian/
+ <p>
+<package/Lintian/ dissects Debian packages and reports bugs and
+policy violations. It contains automated checks for many aspects of
+Debian policy as well as some checks for common errors. The use of
+<package/lintian/ has already been discussed in <ref
+id="upload-checking"> and <ref id="lintian-reports">.
+
+
+ <sect id="debhelper">
+ <heading><package/debhelper/
+ <p>
+<package/debhelper/ is a collection of programs that can be used in
+<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 <package/debmake/, <package/debhelper/ is broken into
+several small, granular commands which act in a consistent manner. As
+such, it allows a greater granularity of control than
+<package/debmake/.
+
+
+ <sect id="debmake">
+ <heading><package/debmake/
+ <p>
+<package/debmake/, a pre-cursor to <package/debhelper/, is a
+less granular <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/.
+ <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="cvs-buildpackage">
+ <heading><package/cvs-buildpackage/
+ <p>
+<package/cvs-buildpackage/ provides the capability to inject or
+import Debian source packages into a CVS repository, build a Debian
+package from the CVS repository, and helps in integrating upstream
+changes into the repository.
+ <p>
+These utilities provide an infrastructure to facilitate the use of CVS
+by Debian maintainers. This allows one to keep separate CVS branches
+of a package for <em/stable/, <em/unstable/, and possibly
+<em/experimental/ distributions, along with the other benefits of a
+version control system.
+
+
+ <sect id="dupload">
+ <heading><package>dupload</package>
+ <p>
+<package/dupload/ is a package and a script to automagically upload
+Debian packages to the Debian archive, to log the upload, and to send
+mail about the upload of a package. You can configure it for new
+upload locations or methods.
+
+
+ <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 say, i.e.,
+<tt>dpkg-buildpackage -rfakeroot</tt> as a user.
+
+
+ <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>, which will
+manipulate your <file>debian/changelog</file> file from the
+command-line, and <prgn>build</prgn>, which is a wrapper around
+<prgn>dpkg-buildpackage</prgn>.
+
+
+ <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.
+
+
+ </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:
+-->
~ianmdlvl / developers-reference.git / blobdiff