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