X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=2ba3c0c7c37ab85428c0e26fc64dfb00ea0cd4f7;hp=53ee4104d9e1a139f452e7f837f1b2b001500280;hb=0c1a32b72e934f36cc741c58764d9935e0a11fd6;hpb=95ea0c14fdc37e203e990ae8b8eee26d95c466f6 diff --git a/developers-reference.sgml b/developers-reference.sgml index 53ee410..2ba3c0c 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,518 +1,887 @@ - - - - + + %versiondata; + + +]> + - - -Debian Developer's Reference -<author>Christian Schwarz <email/schwarz@debian.org/ -<author>based on earlier documents by Ian Jackson <email/ijackson@gnu.ai.mit.edu/ -<version>version 2.4.1.0, 14 April 1998 + <book> -<copyright>Copyright ©1997,1998 Christian Schwarz. -<p> + <title>Debian Developer's Reference + <author>Adam Di Carlo, current maintainer <email/aph@debian.org/ + <author>Christian Schwarz <email/schwarz@debian.org/ + <author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/ + <version>ver. &version;, &date; + <copyright> + <copyrightsummary> +copyright ©1998, 1999 Adam Di Carlo</copyrightsummary> + <copyrightsummary> +copyright ©1997, 1998 Christian Schwarz</copyrightsummary> + <p> This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. -<p> - + <p> This is distributed in the hope that it will be useful, but <em>without any warranty</em>; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. -<p> - + <p> A copy of the GNU General Public License is available as -<tt>/usr/doc/copyright/GPL</tt> in the Debian GNU/Linux -distribution or on the World Wide Web at -<tt>http://www.gnu.org/copyleft/gpl.html</tt>. You can also obtain it -by writing to the Free Software Foundation, Inc., 59 Temple Place - -Suite 330, Boston, MA 02111-1307, USA. -<p> +<file>/usr/doc/copyright/GPL</file> in the Debian GNU/Linux distribution +or on the World Wide Web at <url +id="http://www.gnu.org/copyleft/gpl.html" name="the GNU website">. +You can also obtain it by writing to the Free Software Foundation, +Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + <toc detail="sect2"> + + <chapt id="scope">Scope of This Document + <p> +The purpose of this document is to provide an overview of the +recommended procedures and the available resources for Debian +developers. + <p> +The procedures discussed within include how to become a maintainer +(<ref id="new-maintainer">); how to upload new packages (<ref +id="upload">); how and when to do ports and interim releases of other +maintainers' packages (<ref id="nmu">); how to move, remove, or orphan +packages (<ref id="archive-manip">); and how to handle bug reports +(<ref id="bug-handling">). + <p> +The resources discussed in this reference include the mailing lists +and servers (<ref id="servers">); a discussion of the structure of the +Debian archive (<ref id="archive">); explanation of the different +servers which accept package uploads (<ref id="upload-master">); and a +discussion of resources which can help maintainers with the quality of +their packages (<ref id="tools">). + <p> +It should be clear that this reference does not discuss the technical +details of the Debian package nor how to generate Debian packages; +that information is discussed in the <url +id="http://www.debian.org/doc/packaging-manuals/packaging.html/" +name="Debian Packaging Manual">. Nor does this reference detail the +standards to which Debian software must comply; that information can +be found in the <url id="http://www.debian.org/doc/debian-policy/" +name="Debian Policy Manual">. + <p> +Furthermore, this document is <em>not an expression of formal +policy</em>. It contains documentation for the Debian system, and +generally agreed-upon best practices. - <toc sect> - <chapt>Applying to Become a Maintainer<p> + <chapt id="new-maintainer">Applying to Become a Maintainer <sect>Getting started <p> - - So, you've read all the documentation, you understand what - everything in the <prgn/hello/ example package is for, and - you're about to Debianise your favourite package. How do - you actually become a Debian developer so that your work can - be incorporated into the Project? - <p> - - Firstly, subscribe to <prgn/debian-devel/ if you haven't - already. Send the word <tt/subscribe/ in the <em/Subject/ - of a mail to <email/debian-devel-REQUEST@lists.debian.org/. - In case of problems contact the list administrator at - <email/listmaster@lists.debian.org/. - <p> - - You should subscribe and lurk for a bit before doing any - coding, and you should post about your intentions to work on - something to avoid duplicated effort. - <p> - - If you do not have a PGP key yet generate one. You should - probably read the PGP manual, as it has much important - information which is critical to its security. Many more - security failures are due to human error than to software - failure or high-powered spy techniques. - <p> - - Due to export restrictions by the United States government - some Debian packages, including PGP, have been moved to an - ftp site outside of the United States. You can find the - current locations of those packages on - <ftpsite/ftp.debian.org/ in the - <ftppath>/pub/debian/README.non-US</> file. - <p> - - If you live in a country where use of cryptography even for - authentication is forbidden then please contact us so we can - make special arrangements. This does not apply in France, - where I believe only encryption and not authentication is - forbidden. - <p> - - <sect>Registering as a Debian developer - <p> - - Before you decide to work in the Debian Project you have to - read the ``Debian Social Contract'' (available on - <tt/www.debian.org/). - <p> - After that, you should send a message to - <email/new-maintainer@debian.org/ to register as an - 'offical' Debian developer so that you will be able to - upload your packages. - <p> - The message should say what you've done and who you are, and - should ask for an account on master and to be subscribed to - debian-private (the developers-only mailing list). It should - contain your PGP or RSA public key (extracted using `pgp - -kxa', in the case of PGP) for the database of keys which is - distributed on the FTP server - (<tt>doc/debian-keyring.tar.gz</tt>). Please be sure to - sign your request message with your chosen PGP or RSA - key. In addition, you have to mention that you've read the - ``Debian Social Contract'' (see above) and you are expected - to know where to find the ``Debian Policy Manual'' and the - ``Debian Packaging Manual.'' - <p> - Please be sure to include your preferred login name on - master (seven characters or less), as well as the E-mail - address at which you'd prefer to be subscribed to - debian-private (typically this will be either your primary - mail address or your new debian.org address). - <p> - You should also include some mechanism by which we can - verify your real-life identity. For example, any of the - following mechanisms would suffice: - - <list compact> - <item>A PGP or RSA key signed by any well-known signature, - such as any current Debian developer. - <item>A scanned (or physically mailed) copy of any formal - documents certifying your identity (such as a birth - certificate, national ID card, U.S. Driver's License, - etc.). Please sign the image with your PGP or RSA key. - </list> - - The following mechanisms are discouraged, but are acceptable if - neither of the first two mechanisms is practical: - <list compact> - <item>A pointer to a phone listing at which you could be - reached (at our expense). This phone listing should - be verifiable independently through external means - such as a national directory-listing service or other - authoritative source. - <item>Any other mechanism by which you can establish your - real-life identity with reasonable certainty. +So, you've read all the documentation, you understand what everything +in the <package/hello/ example package is for, and you're about to +Debianize your favourite piece of software. How do you actually +become a Debian developer so that your work can be incorporated into +the Project? + <p> +Firstly, subscribe to <email/debian-devel@lists.debian.org/ if you +haven't already. Send the word <tt/subscribe/ in the <em/Subject/ of +an email to <email/debian-devel-REQUEST@lists.debian.org/. In case of +problems, contact the list administrator at +<email/listmaster@lists.debian.org/. More information on available +mailing lists can be found in <ref id="mailing-lists">. + <p> +You should subscribe and lurk for a bit before doing any coding, and +you should post about your intentions to work on something to avoid +duplicated effort. + <p> +Another good list to subscribe to is +<email/debian-mentors@lists.debian.org/. See <ref id="mentors"> for +details. The IRC channel <tt/#debian/ on the Linux People IRC network +(i.e., <tt/irc.debian.org/) can also be helpful. + + + <sect id="registering">Registering as a Debian developer + <p> +Before you decide to register with the Debian Project, you will need +to read the <url id="http://www.debian.org/social_contract" +name="Debian Social Contract">. Registering as a developer means that +you agree with and pledge to uphold the Debian Social Contract; it is +very important that maintainers are in accord with the essential ideas +behind Debian GNU/Linux. Reading the <url +id="http://www.gnu.org/gnu/manifesto.html" name="GNU Manifesto"> would +also be a good idea. + <p> +The process of registering as a developer is a process of verifying +your identity and intentions. As the number of people working on +Debian GNU/Linux has grown to over &number-of-maintainers; people and +our systems are used in several very important places we have to be +careful about being compromised. Therefore, we need to verify new +maintainers before we can give them accounts on our servers and +letting them upload packages. + <p> +Registration requires that the following information be sent to +<email/new-maintainer@debian.org/ as part of the registration +application: +<list> + <item> +Your name. + <item> +Your preferred login name on <tt/master/ (seven characters or +less<footnote>It is not clear to the author why logins on +<tt>master</tt> cannot be eight characters or greater. If anyone can +clarify why, I would appreciate it.</footnote>), as well as the email +address at which you'd prefer to be subscribed to +<email/debian-private@lists.debian.org/ (typically this will be either +your primary mail address or your new <tt>debian.org</tt> address). + <item> +A phone number where we can call you. Remember that the new +maintainer team usually calls during evening hours to save on long +distance tolls. Please do not give a work number, unless you are +generally there in the evening. + <item> +A statement of intention, that is, what package(s) you intend to work +on, which Debian port you will be assisting, or how you intend to +contribute to Debian. + <item> +A statement that you have read and agree to uphold the <url +id="http://www.debian.org/social_contract" name="Debian Social +Contract">. + <item> +Some mechanism by which we can verify your real-life identity. For +example, any of the following mechanisms would suffice: +<list> + <item> +A PGP key signed by any well-known signature, such as: +<list> + <item> +Any current Debian developer you have met <em/in real life/. + <item> +Any formal certification service (such as Verisign, etc.) that +verifies your identity. A certification that verifies your email +address, and not you identity, is not sufficient. + </list> + <item> +Alternatively, you may identify yourself with a scanned (or physically +mailed) copy of any formal documents certifying your identity (such as +a birth certificate, national ID card, U.S. Driver's License, etc.). +If emailed, please sign the mail with your PGP key. + </list> </list> - - We're sorry about the inconvenience of requiring proof of - identity, but for the moment, such measures are - unfortunately the only way we can ensure the security and - reliability of our distribution. - <p> - - Once this information is received and processed, you should - be contacted with information about your new Debian - maintainer account. If you don't hear anything within 7-10 - days, please re-send your original message--the - new-maintainer volunteers are typically overworked, and - mistakes do occasionally happen. <p> +If you do not have a PGP key yet, generate one. Every developer needs +a PGP key in order to sign and verify package uploads. You should read +the PGP manual, since it has much important information which is +critical to its security. Many more security failures are due to +human error than to software failure or high-powered spy techniques. + <p> +Our standard is to use <prgn>pgp</prgn> version 2.x. You can use +<prgn/pgp/ version 5, if and only if you make an RSA key. Note that +we are also working with the <prgn/gpg/ team so that we can have a +free alternative to PGP; however, this may take a little bit of time. + <p> +Your PGP key must be at least 1024 bits long. There is no reason to +use a smaller key, and doing so would be much less secure. Your key +must be signed with at least your own user ID. This prevents user ID +tampering. You can do it by executing <tt>pgp -ks +<var>your_userid</var></tt>. + <p> +If your PGP key isn't on public key servers such as +<tt>pgp5.ai.mit.edu</tt>, please read the documentation available +locally <tt>/usr/doc/pgp/keyserv.doc</tt>. That document contains +instructions on how to put your key on the public key servers. The +New Maintainer Group will put your public key on the servers if it +isn't already there. + <p> +Due to export restrictions by the United States government some Debian +packages, including PGP, have been moved to an ftp site outside of the +United States. You can find the current locations of those packages on +<ftpsite/ftp.debian.org/ or <ftpsite/ftp.us.debian.org/ in the +<ftppath>/pub/debian/README.non-US</ftppath> file. + <p> +Some countries restrict the use of cryptographic software by their +citizens. This need not impede one's activities as a Debian package +maintainer however, as it may be perfectly legal to use cryptographic +products for authentication, rather than encryption purposes (as is +the case in France). The Debian Project does not require the use of +cryptography <em/qua/ cryptography in any manner. If you live in a +country where use of cryptography even for authentication is forbidden +then please contact us so we can make special arrangements. + <p> +Once you have all your information ready, and your public key is +available on public key servers, send a message to +<email/new-maintainer@debian.org/ to register as an offical Debian +developer so that you will be able to upload your packages. This +message must contain all the information discussed above. The message +must also contain your PGP or RSA public key (extracted using <tt>pgp +-kxa</tt> in the case of PGP) for the database of keys which is +distributed from <ftpsite/ftp.debian.org/ in +<ftppath>/pub/debian/doc/debian-keyring.tar.gz</ftppath>, or the +<package/debian-keyring/ package. Please be sure to sign your request +message with your chosen public key. + <p> +Once this information is received and processed, you should be +contacted with information about your new Debian maintainer account. +If you don't hear anything within 7-14 days, please send a followup +message asking if your original application was received. Do <em/not/ +re-send your original application, that will just confuse the +new-maintainer team. Please be patient, especially near release +points; mistakes do occasionally happen, and people do sometimes run +out of volunteer time. - <sect>Debian Mentors - <p> - - There is a mailing list called <tt/debian-mentors/ which has - been set up for newbie maintainers who seek help with - initial packaging and other developer-related issues. - <p> - Every new developer is invited to subscribe to that list - (see <ref id="mailing-lists"> for details). + + <sect id="mentors">Debian Mentors <p> - Those who prefer one-on-one help (e.g., via private emails) - should also post to that list and an experienced developer - will volunteer to help. +A mailing list called <email/debian-mentors@lists.debian.org/ which +has been set up for novice maintainers who seek help with initial +packaging and other developer-related issues. Every new developer is +invited to subscribe to that list (see <ref id="mailing-lists"> for +details). <p> - - - <chapt>Internet Servers<p> +Those who prefer one-on-one help (e.g., via private email) should +also post to that list and an experienced developer will volunteer to +help. - <sect id="mailing-lists">Mailing lists<p> - The mailing list server is at <tt/lists.debian.org/. Mail - <tt/debian-<var/foo/-REQUEST@lists.debian.org/, where - <tt/debian-<var/foo// is the name of the list, with the word - <tt/subscribe/ in the Subject to subscribe or - <tt/unsubscribe/ to unsubscribe. - <p> - When replying to messages on the mailing list, please do not - send a carbon copy (<tt/CC/--this does not mean `courtesy - copy') to the original poster. Anyone who posts to a - mailing list should read it to see the responses. - <p> - In addition, all messages should usually only be sent to one - of the following mailing lists: <tt/debian-devel/, - <tt/debian-policy/, <tt/debian-user/, <tt/debian-announce/, - <tt/debian-devel-announce/. + <chapt id="user-maint">Maintaining Your Debian Information + + <sect id="key-maint">Maintaining Your Public Key <p> - As ever on the net, please trim down the quoting of articles - you're replying to. In general, please adhere to the usual - conventions for posting messages. +Be very careful with your private keys. Do not place them on any +public servers. Back them up. Read the documentation that comes with +your software (either PGP or GNUPG); read the FAQs too, for good +measure. <p> - - <sect>The master server +If you add or remove signatures from your public key, or add or remove +user identities, you need to update the key servers and mail your +public key to <email>keyring-maint@debian.org</email>. +The same key extraction routines discussed in <ref id="registering"> +apply. <p> +You can find a more in-depth discussion of Debian key maintenance in +the documentation for the <package>debian-keyring</package> package. + + <sect>Retiring Gracefully + <p> +If you choose to leave the Debian project, you should make sure you do +the following steps: +<enumlist> + <item> +Orphan all your packages, as described in <ref id="orphaning">. + <item> +Send an email about how you are leaving the project to +<email>debian-private@lists.debian.org</email>. + <item> +Notify the Debian key ring maintainers that you are leaving by emailing +to <email>keyring-maint@debian.org</email>. + </enumlist> - <sect>The FTP servers - <p> - <sect>The WWW servers + <chapt id="servers">Mailing Lists, Servers, and Other Machines + <p> +In this chapter you will find a very brief road map of the Debian +mailing lists, the main Debian servers, and other Debian machines +which may be available to you as a developer. + + <sect id="mailing-lists">Mailing lists + <p> +The mailing list server is at <tt/lists.debian.org/. Mail +<tt/debian-<var/foo/-REQUEST@lists.debian.org/, where +<tt/debian-<var/foo// is the name of the list, with the word +<tt/subscribe/ in the <em/Subject/ to subscribe to the list or +<tt/unsubscribe/ to unsubscribe. More detailed instructions on how to +subscribe and unsubscribe to the mailing lists can be found at <url +id="http://www.debian.org/MailingLists/subscribe">, <url +id="ftp://ftp.debian.org/debian/doc/mailing-lists.txt"> or locally in +<file>/usr/doc/debian/mailing-lists.txt</file> if you have the +<package>doc-debian</package> package installed. + <p> +When replying to messages on the mailing list, please do not send a +carbon copy (<tt/CC/) to the original poster unless they explicitly +request to be copied. Anyone who posts to a mailing list should read +it to see the responses. + <p> +In addition, all messages should usually only be sent to one of the +following mailing lists: <email/debian-devel@lists.debian.org/, +<email/debian-policy@lists.debian.org/, +<email/debian-user@lists.debian.org/, +<email/debian-announce@lists.debian.org/, or +<email/debian-devel-announce@lists.debian.org/. Additional mailing +lists are available for special purposes; see <url +id="http://www.debian.org/MailingLists/subscribe">. Cross-posting +(sending the same message to multiple lists) is discouraged. + <p> +<email/debian-private@lists.debian.org/ is a special mailing lists for +private discussions amongst Debian developers. It is meant to be used +for posts which for whatever reason should not be published +publically. As such, it is a low volume list, and users are urged not +to use <email/debian-private@lists.debian.org/ unless it is really +necessary. Moreover, do <em/not/ forward email from that list to +anyone. + <p> +As ever on the net, please trim down the quoting of articles you're +replying to. In general, please adhere to the usual conventions for +posting messages. + <p> +Online archives of mailing lists are available at <url +id="http://www.debian.org/Lists-Archives/">. + + <sect id="server-machines">Debian servers + <p> +Debian servers are well known servers which serve critical functions +in the Debian project. Every developer should know what these servers +are and what they do. + <p> +If you have a problem with the operation of Debian server, and you +think that the system operators need to be notified of this problem, +please find the contact address for the particular role at <url +id="http://www.debian.org/devel/maintainer_contacts">. If you have a +non-operating problems (such as packages to be remove, suggestions for +the web site, etc.), generally you'll report a bug against a +``pseudo-package''. See <ref id="submit-bug"> for information on how +to submit bugs. + + <sect1 id="servers-master">The master server + <p> +The master server, <tt/master.debian.org/, holds the canonical copy +of the Debian archive (excluding the non-U.S. packages). Generally, +package uploads go to this server; see <ref id="upload">. + <p> +<tt/master.debian.org/ is the canonical location for the Bug Tracking +System (BTS). If you plan on doing some statistical analysis or +processing of Debian bugs, this would be the place to do it. Please +describe your plans on <email/debian-devel@lists.debian.org/ before +implementing anything, however, to reduce unnecessary duplication of +effort or wasted processing time. + <p> +All Debian developers have accounts on <tt/master.debian.org/. Please +take care to protect your password to this machine. Try to avoid +login or upload methods which send passwords over the Internet in the +clear. + <p> +If you find a problem with <tt/master.debian.org/ such as disk full, +suspicious activity, or whatever, send an email to +<email>debian-admin@debian.org</email>. Problems with the Debian FTP +archive generally need to be reported as bugs against the +<package>ftp.debian.org</package> pseudo-package or an email to +<email>ftpmaster@debian.org</email>, but also see the procedures in +<ref id="archive-manip">. + + <sect1 id="servers-www">The WWW servers + <p> +The main web server, <tt/www.debian.org/, is also known as +<tt/va.debian.org/. All developers are given accounts on this +machine. + <p> +If you have some Debian-specific information which you want to serve +up on the web, you can do do this by putting material in the +<file>public_html</file> directory under your home directory. You can do +this on either <tt/va.debian.org/ or <tt/master.debian.org/. Any +material you put in those areas are accessible via the URLs +<tt>http://www.debian.org/~<var>user-id</var>/</tt> and +<tt>http://master.debian.org/~<var>user-id</var>/</tt>, respectively. +Generally, you'll want to use <tt/va/, for the <tt/www.debian.org/ +address, although in some cases you may need to put it on <tt/master/. +Please do not put any material on Debian servers not relating to +Debian, unless you have prior permission. Send mail to +<email/debian-devel@lists.debian.org/ if you have any questions. + <p> +If you find a problem with the Debian web server, you should generally +submit a bug against the pseudo-package, +<package>www.debian.org</package>. First check whether or not someone +else has already reported the problem on the <url +id="http://www.debian.org/Bugs/db/pa/lwww.debian.org.html" name="Bug +Tracking System">. + + + <sect1 id="servers-cvs">The CVS server <p> +<tt/cvs.debian.org/ is also known as <tt/va.debian.org/, discussed +above. If you need the use of a publically accessible CVS server, for +instance, to help coordinate work on a package between many different +developers, you can request a CVS area on the server. + <p> +Generally, <tt/cvs.debian.org/ offers a combination of local CVS +access, anonymous client-server read-only access, and full +client-server access through <prgn>ssh</prgn>. Also, the CVS area can +be accessed read-only via the Web at <url +id="http://cvs.debian.org/cgi-bin/cvsweb">. + <p> +To request a CVS area, send a request via email to +<email>debian-admin@debian.org</email>. Include the name of the +requested CVS area, what <tt>va.debian.org</tt> user account should +own the CVSROOT, and why you need it. + + + <sect1 id="servers-mirrors">Mirrors of Debian servers + <p> +The web and FTP servers have several mirrors available. Please do not +put heavy load on the canonical FTP or web servers. Ideally, the +canonical servers only mirror out to a first tier of mirrors, and all +user access is to the mirrors. This allows Debian to better spread +its bandwidth requirements over several servers and networks. Note +that newer push mirroring techniques ensure that mirrors are as +up-to-date as they can be. + <p> +The main web page listing the available public FTP (and, usually, +HTTP) servers can be found at <url +id="http://www.debian.org/distrib/ftplist">. More information +concerning Debian mirrors can be found at <url +id="http://www.debian.org/mirror">. This useful page includes +information and tools which can be helpful if you are interested in +setting up your own mirror, either for internal or public access. + <p> +Note that mirrors are generally run by third-parties who are +interested in helping Debian. As such, developers generally do not +have accounts on these machines. + <p> +Please do not mirror off of <tt/master.debian.org/. This host already +has too much load. Check the sites above for information, or email +<email/debian-devel@lists.debian.org/. + + + <sect id="other-machines">Other Debian Machines + <p> +There are other Debian machines which may be made available to you. +You can use these for Debian-related purposes as you see fit. Please +be kind to system administrators, and do not use up tons and tons of +disk space, network bandwidth, or CPU without first getting the +approval of the local maintainers. Usually these machines are run by +volunteers. Generally, these machines are for porting activities. + <p> +Aside from the servers mentioned in <ref id="server-machines">, the +following machines are, or may be made, available to you. If an email +address is listed, generally that person is the party to contact about +issues on the machine. Otherwise, the machine is probably managed by +<email>debian-admin@debian.org</email>. + +<taglist> + <tag><tt>faure.debian.org</tt></tag> + <item> +An Alpha; if you have an account on <tt>master</tt>, you probably +already have an account here. + + <tag><tt>kubrick.debian.org</tt></tag> + <item> +A SPARC; if you have an account on <tt>master</tt>, you probably +already have an account here. + + <tag><tt>pandora.debian.org</tt></tag> + <item> +An i386; if you have an account on <tt>master</tt>, you probably +already have an account here. + + <tag><tt>albert.debian.org</tt></tag> + <item> +An Alpha; you probably want to use <tt>faure</tt> instead, but you may +request an account from <email>debian-admin@debian.org</email>. + + <tag><tt>powerpc.debian.org</tt></tag> + <item> +A PowerPC; also known as <tt>tervola.infodrom.north.de</tt>. You may +request an account from <email>joey@debian.org</email> or +<email>koptein@debian.org</email>. + + <tag><tt>m68k.debian.org</tt></tag> + <item> +A Motorola 6800x0 machine; you may request an account from +<email>joey@debian.org</email> or <email>james@nocrew.org</email>. +Runs an autobuilder. + + <tag><tt>alpha.debian.nl</tt></tag> + <item> +An Alpha; you may request an account from +<email>debian@cistron.nl</email>. + + <tag><tt>xia0[123].kachinatech.com</tt></tag> + <item> +SPARC and UltraSPARC machines. <tt>xia0[12]</tt> are used for +automatic compilation; you can request an account on xia03 (an +UltraSPARC) from <email>wdeng@kachinatech.com</email>. + + </taglist> + + + + <chapt id="archive">The Debian Archive - <chapt>The Debian Archive<p> - <sect>Overview <p> +The Debian GNU/Linux distribution consists of a lot of Debian packages +(<tt/.deb/'s, currently around &number-of-pkgs;) and a few additional files +(documentation, installation disk images, etc.). + <p> +Here is an example directory tree of a complete Debian distribution: + <p> +<example> +main/ +main/binary-all/ +main/binary-all/admin/ +main/binary-all/base/ +main/binary-all/comm/ +main/binary-all/devel/ + ... +main/binary-i386/ +main/binary-i386/admin/ +main/binary-i386/base/ + ... +main/binary-m68k +main/binary-m68k/admin/ +main/binary-m68k/base/ + ... +main/source/ +main/source/admin/ +main/source/base/ + ... +main/disks-i386/ +main/disks-m68k/ + ... + +contrib/ +contrib/binary-all/ +contrib/binary-i386/ +contrib/binary-m68k/ + ... +contrib/source/ + +non-free/ +non-free/binary-all/ +non-free/binary-i386/ +non-free/binary-m68k/ + ... +non-free/source/ +</example> + <p> +As you can see, the top-level directory of the distribution contains +three directories, namely <em/main/, <em/contrib/, and +<em/non-free/. These directories are called <em/sections/. + <p> +In each section, there is a directory with the source packages +(source), a directory for each supported architecture +(<tt/binary-i386/, <tt/binary-m68k/, etc.), and a directory for +architecture independent packages (<tt/binary-all/). + <p> +The <em/main/ section contains additional directories which holds the +disk images and some essential pieces of documentation required for +installing the Debian distribution on a specific architecture +(<tt/disks-i386/, <tt/disks-m68k/, etc.). + <p> +The <em/binary/ and <em/source/ directories are divided further into +<em/subsections/. + - The Debian GNU/Linux distribution consists of a lot of - Debian packages (<tt/.deb/'s, currently more than 1000) and - a few additional files (documentation, installation disk - images, etc.). - <p> - Here is an example directory tree of a complete Debian - distribution: - <example> - main/ - main/binary-all/ - main/binary-all/admin/ - main/binary-all/base/ - main/binary-all/comm/ - main/binary-all/devel/ - ... - main/binary-i386/ - main/binary-m86k/ - ... - main/source/ - main/disks-i386/ - main/disks-m68k/ - ... - - contrib/ - contrib/binary-all/ - contrib/binary-i386/ - contrib/binary-m86k/ - ... - contrib/source/ - - non-free/ - non-free/binary-all/ - non-free/binary-i386/ - non-free/binary-m86k/ - ... - non-free/source/ - </example> - <p> - As you can see, the top-level directory of the distribution - contains three directories, namely <em>main</>, - <em>contrib</>, and <em>non-free</>. These directories are - called <em>sections</>. - <p> - In each section, there is a directory with the source - packages (source), a directory for each supported - architecture (binary-i386, binary-m86k, etc.), and a - directory for architecture independent packages - (binary-all). - <p> - The <em/main/ section contains additional directories which - holds the disk images and some essential pieces of - documentation required for installing the Debian - distribution on a specific architecture (disks-i386, - disks-m68k, etc.). - <p> - The <em/binary/ and <em/source/ directories are divided - further into <em/sub-sections/. - <p> - <sect>Sections <p> +The <em>main</em> section is what makes up the <em>official Debian +GNU/Linux distribution</em>. The <em/main/ section is official because +it fully complies with all our guidelines. The other two sections do +not, to different degrees; as such, they are not officially part of +Debian. + <p> +Every package in the main section must fully comply with the <!-- work +around quoting of fragment idendifiers bug <url +id="http://www.debian.org/social_contract#guidelines" name="Debian +Free Software Guidelines"> --> <url +id="http://www.debian.org/social_contract" name="Debian Free Software +Guidelines"> (DFSG) and with all other policy requirements as +described in the <url id="http://www.debian.org/doc/debian-policy/" +name="Debian Policy Manual">. The DFSG is our definition of ``free +software.'' Check out the Debian Policy Manual for details. + <p> +The packages which do not apply to the DFSG are placed in the +<em/non-free/ section. These packages are not considered as part of +the Debian distribution, though we support their use, and we provide +infrastructure (such as our bug-tracking system and mailing lists) for +non-free software packages. + <p> +Packages in the <em/contrib/ section have to comply with the DFSG, but +may fail other requirements. For instance, they may depend on +non-free packages. + <p> +The <url id="http://www.debian.org/doc/debian-policy/" name="Debian +Policy Manual"> contains a more exact definition of the three +sections. The above discussion is just an introduction. + <p> +The separation of the three sections at the top-level of the archive +is important for all people who want to distribute Debian, either via +FTP servers on the Internet or on CD-ROMs: by distributing only the +<em/main/ and <em/contrib/ sections, one can avoid any legal risks. +Some packages in the <em/non-free/ section do not allow commercial +distribution, for example. + <p> +On the other hand, a CD-ROM vendor could easily check the individual +package licenses of the packages in <em/non-free/ and include as many +on the CD-ROMs as he's allowed. (Since this varies greatly from vendor +to vendor, this job can't be done by the Debian developers.) - The <em>main section</> is what makes up the <em>Debian - GNU/Linux distribution</>. This is because the packages in - the other two sections do not fully comply with all our - guidelines. - <p> - For example, every package in the main distribution must - fully comply with the <em>Debian Free Software Guidelines</> - (DFSG) and with all other policy requirements as described - in the <em>Debian Policy Manual</em>. (The DFSG is our - definition of ``free software.'' Check out the Debian Policy - Manual for details.) - <p> - The packages which do not apply to the DFSG are placed in - the <em>non-free</> section. These packages are not - considered as part of the Debian distribution, though we - support their use, and we provide infrastructure (such as - our bug-tracking system and mailing lists) for non-free - software packages. - <p> - Packages in the <em>contrib</> section have to apply to - the DFSG, but fail other requirements. - <p> - (The Debian Policy Manual contains a more exact definition - of the three sections. This is just meant to be an - introduction.) - <p> - The separation of the three sections at the top-level of - the archive is important for all people who want to - distribute Debian, either via FTP servers on the Internet - or on CD-ROMs: by distributing only the <em/main/ and - <em/contrib/ sections, one can avoid any legal risks, - since some packages in the <em/non-free/ section do not - allow commercial distribution, for example. - <p> - On the other hand, a CD-ROM vendor could easily check the - individual package licenses of the packages in <em/non-free/ - and include as many on the CD-ROMs as he's allowed. (Since - this varies from vendor to vendor very much, this job can't - be done by the Debian developers.) - <p> <sect>Architectures <p> +In the first days, the Linux kernel was only available for the Intel +i386 (or greater) platforms, and so was Debian. But when Linux became +more and more popular, the kernel was ported to other architectures, +too. + <p> +The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola +680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC. +The Linux 2.2 kernel supports even more architectures, including ARM +and UltraSPARC. Since Linux supports these platforms, Debian decided +that it should, too. Therefore, Debian has ports underway. In fact, +we also have ports underway to non-Linux kernel. Aside from +<em>i386</em> (our name for Intel x86), there is <em>m68k</em>, +<em>alpha</em>, <em>powerpc</em>, <em>sparc</em>, <em>hurd-i386</em>, +and <em>arm</em>, as of this writing. - In the first days, the Linux kernel was only available for - the Intel i386 (or greater) platforms, and so was - Debian. But when Linux became more and more popular, the - kernel was ported to other architectures, too. - <p> - The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, - M68000 machines (like Atari and Amiga), MIPS, and - PowerPC. - <p> - Debian GNU/Linux 1.3 is only available for Intel - platforms. One of the goals for Debian 2.0 is to support - some of the other architectures, too. <p> +Debian GNU/Linux 1.3 is only available as <em>i386</em>. Debian 2.0 +shipped for <em>i386</em> and <em>m68k</em> architectures. Debian 2.1 +ships for the <em>i386</em>, <em>m68k</em>, <em>alpha</em>, and +<em>sparc</em> architectures. - <sect>Sub sections - <p> - The sections <em/main/, <em/contrib/, and <em/non-free/ are - split into <em/sub sections/, to simplify the installation - process and the maintainance of the archive. - <p> + <sect>Subsections + <p> +The sections <em/main/, <em/contrib/, and <em/non-free/ are split into +<em/subsections/ to simplify the installation process and the +maintainance of the archive. Subsections are not formally defined, +excepting perhaps the `base' subsection. Subsections exist simply +to simplify the organization and browsing of available packages. +Please check the current Debian distribution to see which sections are +available. + <sect>Packages <p> +There are two types of Debian packages, namely <em/source/ and +<em/binary/ packages. + <p> +Source packages consist of either two or three files: a <tt/.dsc/ +file, and either a <tt/.tar.gz/ file or both an <tt/.orig.tar.gz/ and +a <tt/.diff.gz/ file. + <p> +If a package is developed specially for Debian and is not distributed +outside of Debian, there is just one <tt/.tar.gz/ file which contains +the sources of the program. If a package is distributed elsewhere +too, the <tt/.orig.tar.gz/ file stores the so-called <em/upstream +source code/, that is the source code that's distributed from the +<em/upstream maintainer/ (often the author of the software). In this +case, the <tt/.diff.gz/ contains the changes made by the Debian +maintainer. + <p> +The <tt/.dsc/ lists all the files in the source package together with +checksums (md5sums) and some additional info about the package +(maintainer, version, etc.). - There are two types of Debian packages, namely <em/source/ - and <em/binary/ packages. - <p> - Source packages consist of either two or three files: a - <tt/.dsc/ file, and either one <tt/.tar.gz/ file or a - <tt/.orig.tar.gz/ and a <tt/.diff.gz/ file. - <p> - If a package is developed specially for Debian and is not - distributed outside of Debian, there is just one - <tt/.tar.gz/ file which contains the sources of the program. - <p> - If a package is distributed elsewhere too, the - <tt/.orig.tar.gz/ file stores the so-called <em/upstream - source code/, that is the source code that's distributed - from the <em/upstream maintainer/ (author). In this case, - the <tt/.diff.gz/ contains the changes made by the Debian - maintainer. - <p> - The <tt/.dsc/ lists all components of the source package - together with checksums (md5sums) and some additional info - about the package (maintainer, version, etc.). - <p> <sect>Distribution directories <p> +The directory system described in the previous chapter, are themselves +contained within <em/distribution directories/. Every distribution is +contained in the <tt/dists/ directory in the top-level of the Debian +archive itself (the symlinks from the top-level directory to the +distributions themselves are for backwards compatability and are +deprecated). + <p> +To summarize, the Debian archive has a root directory within an FTP +server. For instance, at the mirror site, +<ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is +contained in <ftppath>/debian</ftppath>, which is a common location +(another is <ftppath>/pub/debian</ftppath>). + <p> +Within that archive root, the actual distributions are contained in +the <tt/dists/ directory. Here is an overview of the layout: + <p> +<example> +<var>archive root</var>/dists/<var>distribution</var>/<var>section</var>/<var>architecture</var>/<var>subsection</var>/<var>packages</var> +</example> + +Extrapolating from this layout, you know that to find the i386 base +packages for the distribution <em/slink/, you would look in +<ftppath>/debian/dists/slink/main/binary-i386/base/</ftppath>. + + <sect1>Stable, unstable, and sometimes frozen + <p> +There is always a distribution called <em/stable/ (residing in +<tt>dists/stable</tt>) and one called <em/unstable/ (residing in +<tt>dists/unstable</tt>). This reflects the development process of the +Debian project. + <p> +Active development is done in the <em/unstable/ distribution (that's +why this distribution is sometimes called the <em/development +distribution/). Every Debian developer can update his or her packages +in this distribution at any time. Thus, the contents of this +distribution change from day-to-day. Since no special effort is done +to test this distribution, it is sometimes ``unstable.'' + <p> +After a period of development, the <em/unstable/ distribution is +copied in a new distribution directory, called <em/frozen/. When that +occurs, no changes are allowed to the frozen distribution except bug +fixes; that's why it's called ``frozen.'' After another month or a +little longer, the <em/frozen/ distribution is renamed to <em/stable/, +overriding the old <em/stable/ distribution, which is removed at that +time. + <p> +This development cycle is based on the assumption that the +<em/unstable/ distribution becomes <em/stable/ after passing a period +of testing as <em/frozen/. Even once a distribution is considered +stable, a few bugs inevitably remain--that's why the stable +distribution is updated every now and then. However, these updates are +tested very carefully and have to be introduced into the archive +individually to reduce the risk of introducing new bugs. You can find +proposed additions to <em/stable/ in the <tt/proposed-updates/ +directory. Those packages in <tt/proposed-updates/ that pass muster +are periodically moved as a batch into the stable distribution and the +revision level of the stable distribution is incremented (e.g., `1.3' +becomes `1.3r1', `2.0r2' becomes `2.0r3', and so forth). + <p> +Note that development under <em/unstable/ is continued during the +``freeze'' period, since a new <em/unstable/ distribution is be +created when the older <em/unstable/ is moved to <em/frozen/. +Another wrinkle is that when the <em/frozen/ distribution is offically +released, the old stable distribution is completely removed from the +Debian archives (although you can still find it from servers which +serve up older, obsolete distributions). + <p> +In summary, there is always a <em/stable/ and an <em/unstable/ +distribution available, and the <em/frozen/ distribution shows up for +a month or so from time to time. + + + <sect1>Experimental + <p> +The <em/experimental/ distribution is a specialty distribution. It is +not a full distribution in the same sense that `stable' and `unstable' +are. Instead, it is meant to be a temporary staging area for highly +experimental software where there's a good chance that the software +could break your system. Users who download and install packages from +<em/experimental/ are expected to have been duly warned. In short, +all bets are off for the <em/experimental/ distribution. + <p> +Developers should be very selective in the use of the +<em/experimental/ distribution. Even if a package is highly unstable, +it could well still go into <em/unstable/; just state a few warnings +in the description. However, if there is a chance that the software +could do grave damage to a system, it might be better to put it into +<em/experimental/. + <p> +For instance, an experimental encrypted file system should probably go +into <em>experimental</em>. A new, beta, version of some software +which uses completely different configuration might go into +<em>experimental</em> at the maintainer's discretion. New software +which isn't likely to damage your system can go into +<em>unstable</em>. If you are working on an incompatible or complex +upgrade situation, you can also use <em>experimental</em> as a staging +area, so that testers can get early access. + <p> +However, using <em>experimental</em> as a personal staging area is not +always the best idea. You can't replace or upgrade the files in there +on your own (<prgn>dinstall</prgn> and the Debian archive maintainers +do that). Additionally, you'll have to remember to ask the archive +maintainers to delete the package one you have uploaded it to +<em>unstable</em>. Using your personal web space on +<tt>va.debian.org</tt> is generally a better idea, so that you put +less strain on the Debian archive maintainers. + - If you have a look at the Debian FTP server or one of its - mirrors, you'll discover that there is one additional - directory level on top of the directory tree, as described - in the previous chapter. These directories are the - <em/distribution directories/. - <p> - There is always a distribution called <em/stable/ and one - called <em/unstable/. This reflects the development process - of the Debian project: - <p> - The ``development'' is done in the <em/unstable/ - distribution (that's why this distribution is sometimes - called <em/development distribution/). Every Debian - developer can update his/her packages in this distribution - at any time. Thus, the contents of this distribution changes - from day to day and since no special effort is done to test - this distribution it's sometimes ``unstable.'' - <p> - After about two months of development, the <em/unstable/ - distribution is copied in a new distribution directory, - called <em/frozen/. After that, no changes are allowed to - the frozen distribution, except bug fixes. (That's why it's - called ``frozen.'') - <p> - After another month or a little longer, the <em/frozen/ - distribution is renamed to <em/stable/, overriding the old - <em/stable/ distribution, which is removed at that time. - <p> - This development cycle is based on the assumption, that the - once `unstable' distribution finally becomes `stable' after - passing one month of testing. Unfortunately, a few bugs - still remain--that's why the stable distribution is updated - every few weeks. However, these updates are tested very - carefully and have to be acknowledged individually to reduce - the risk of introducing new bugs. - <p> - Note, that development is continued during the ``freeze'' - period, since a new ``unstable'' distribution will be - created at that time. - <p> - In summary, there is always a <em/stable/ and an - <em/unstable/ distribution available and the <em/frozen/ - distribution shows up for a month from time to time. - <p> - - <sect>Release code names - <p> - Every released Debian distribution has a <em/code name/: - Debian 1.1 is called <em/buzz/, Debian 1.2 <em/rex/, Debian - 1.3 <em/bo/, Debian 2.0 <em/hamm/, etc. - <p> - Since the Debian has an open development (i.e. everyone can - participate and follow the development) even the - ``development versions'' (unstable) are distributed via the - Internet on the Debian FTP server. This FTP server is - mirrored by lots of other systems. Thus, if we'd call the - directory which contains the development version simply - `unstable', then we would have to rename it to `stable' when - the version is released, which would cause all FTP mirrors - to re-get the whole distribution (which is already very - large!). - <p> - On the other hand, if we would call the distribution - directories <em>Debian-x.y</em> from the beginning, people - would think that Debian release <em>x.y</> is - available. (This happened in the past, where a CD-ROM vendor - built a Debian 1.0 CD-ROM based on a pre-1.0 development - version. That's the reason why the first official Debian - release was 1.1, and not 1.0.) - <p> - Thus, the names of the distribution directories in the - archive should stay the same during the development period - and after the release but there may be symbolic links, which - can be changed. - <p> - That's why the distribution directories use the <em/code - names/ and there are symbolic links <em/stable/, - <em/unstable/, <em/frozen/, etc. which point to the - appriopriate release directories. - <p> - - <chapt>Package uploads<p> + <sect id="codenames">Release code names + <p> +Every released Debian distribution has a <em/code name/: Debian 1.1 is +called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0, +`hamm'; Debian 2.1, `slink'; and Debian 2.2, `potato'. There is +also a ``pseudo-distribution'', called `sid' which is contains +packages for architectures which are not yet officially supported or +released by Debian. These architectures are planned to be integrated +into the mainstream distribution at some future date. + <p> +Since the Debian has an open development model (i.e., everyone can +participate and follow the development) even the unstable distribution +is distributed via the Internet on the Debian FTP and HTTP server +network. Thus, if we had called the directory which contains the +development version `unstable', then we would have to rename it +to `stable' when the version is released, which would cause all FTP +mirrors to re-retrieve the whole distribution (which is already very +large!). + <p> +On the other hand, if we called the distribution directories +<em>Debian-x.y</em> from the beginning, people would think that Debian +release <em>x.y</em> is available. (This happened in the past, where a +CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development +version. That's the reason why the first official Debian release was +1.1, and not 1.0.) + <p> +Thus, the names of the distribution directories in the archive are +determined by their code names and not their release status (i.e., +`slink'). These names stay the same during the development period +and after the release; symbolic links, which can be changed, are made +to indicate the currently released stable distribution. That's why +the real distribution directories use the <em/code names/ and symbolic +links for <em/stable/, <em/unstable/, and <em/frozen/ point to the +appropriate release directories. + + + <chapt id="upload">Package uploads <sect>Announcing new packages <p> - If you want to create a new package for the Debian - distribution, you have to send a short email to - <em/debian-devel/ describing your plans before you upload - the new package. - <p> - This has the following advantages: - +If you want to create a new package for the Debian distribution, you +should first check the <url +id="http://www.debian.org/doc/prospective-packages.html" +name="Work-Needing and Prospective Packages (WNPP)"> list. Checking +the WNPP ensures that no one is already working on packaging that +software, and that effort is not duplicated. Assuming no one else is +already working on your prospective package, you must then send a +short email to <email/debian-devel@lists.debian.org/ describing your +plan to create a new package. You should set the subject of the email +to ``intent to package <var/foobar/'', substituting the name of the new +package for <var/foobar/. + <p> +There are a number of reasons why we ask maintainers to follow these +steps: <list compact> - <item>It helps the (potentially new) maintainer to tap - into the experience of people on the list, and lets - them know if any one else is working on it already - <p> - <item>It lets other people thinking about working on the - package know that there already is a volunteer, and - efforts may be shared - <p> - <item>It lets the rest of the maintainers know more about - the package than the one line description and the - changelog entry "Initial version" that generally gets - posted to debian-devel-changes by default - <p> - <item>It is helpful to the people who live off unstable - (and form our first line of testers); we should - encourage these people - <p> - <item>I think the announcements gives us a better feel of - what is going on, and what is new, in the project. - <p> - <item>We should not dismiss anybody who installs from - unstable and helps us debug our packages as "fools, - fools, you installed from unstable; you deserve what - you get"--we derive a certain benefit from the alpha - testers - <p> - <item>If we appreciate alpha testers, than any name - changes have to be backwards compatible with the - people who already installed the old package (conflict - and replace old package name at a minimum) + <item> +It helps the (potentially new) maintainer to tap into the experience +of people on the list, and lets them know if any one else is working +on it already. + <item> +It lets other people thinking about working on the package know that +there already is a volunteer, and efforts may be shared. The ``intent +to package'' message to <email/debian-devel@lists.debian.org/ will be +picked up the the WNPP maintainer, and your intention will be +published in subsequent versions of the WNPP document. + <item> +It lets the rest of the maintainers know more about the package than +the one line description and the changelog entry ``Initial version'' +that generally gets posted to <tt/debian-devel-changes/ by default. + <item> +It is helpful to the people who live off unstable (and form our first +line of testers); we should encourage these people. + <item> +The announcements give maintainers and other interested parties a +better feel of what is going on, and what is new, in the project. </list> - - <sect>Uploading a package - <p> + + + <sect id="uploading">Uploading a package <sect1>Generating the changes file <p> - - When a package is uploaded to the Debian FTP archive, it - must be accompanied by a <tt/.changes/ file which gives - directions for its handling. This is usually generated by - <prgn/dpkg-genchanges/. +When a package is uploaded to the Debian FTP archive, it must be +accompanied by a <tt/.changes/ file, which gives directions to the +archive maintainers for its handling. This is usually generated by +<prgn/dpkg-genchanges/ during the normal package build process. <p> - - This file is a control file with the following fields: - <list compact> +The changes file is a control file with the following fields: + <p> +<list compact> <item><tt/Format/ <item><tt/Date/ <item><tt/Source/ @@ -527,232 +896,1063 @@ Suite 330, Boston, MA 02111-1307, USA. <item><tt/Files/ </list> <p> +All of these fields are mandatory for a Debian upload. See the list +of control fields in the <url +id="http://www.debian.org/doc/packaging-manuals/packaging.html/" +name="Debian Packaging Manual"> for the contents of these fields. +Only the <tt/Distribution/ field is discussed here, since it relates +to the archive maintenance policies. - All of them are mandatory for a Debian upload. See the - list of control fields in the <em/Debian Packaging Manual/ - for the contents of these fields. + <sect1 id="upload-dist">Picking a distribution + <p> +Notably, the <tt/Distribution/ field, which originates from the +<file>debian/changelog</file> file, indicates which distribution the +package is intended for. There are four possible values for this +field: `stable', `unstable', `frozen', or `experimental'; these values +can also be combined. For instance, if you have a crucial security +fix release of a package, and the package has not diverged between the +<em/stable/ and <em/unstable/ distributions, then you might put +`stable unstable' in the <file>changelog</file>'s <tt/Distribution/ field. +Or, if Debian has been frozen, and you want to get a bug-fix release +into <em/frozen/, you would set the distribution to `frozen unstable'. +(See <ref id="upload-frozen"> for more information on when to upload to +<em/frozen/.) Note that setting the distribution to `stable' means +that the package will be placed into the <tt>proposed-updates</tt> +directory of the Debian archive for further testing before it is +actually included in <em/stable/. Also note that it never makes sense +to combine the <em/experimental/ distribution with anything else. <p> +The first time a version is uploaded which corresponds to a particular +upstream version the original source tar file should be uploaded and +included in the <tt/.changes/ file; subsequent times the very same tar +file should be used to build the new diffs and <tt/.dsc/ files, and it +need not then be uploaded. + <p> +By default <prgn/dpkg-genchanges/ and <prgn/dpkg-buildpackage/ will +include the original source tar file if and only if the Debian +revision part of the source version number is <tt/0/ or <tt/1/, +indicating a new upstream version. This behaviour may be modified by +using <tt/-sa/ to always include it or <tt/-sd/ to always leave it +out. + <p> +If no original source is included in the upload then the original +source tar-file used by <prgn/dpkg-source/ when constructing the +<tt/.dsc/ file and diff to be uploaded <em/must/ be byte-for-byte +identical with the one already in the archive. If there is some +reason why this is not the case then the new version of the original +source should be uploaded, possibly by using the <tt/-sa/ flag. + + <sect2 id="upload-frozen">Uploading to <em/frozen/ + <p> +The Debian freeze is a crucial time for Debian. It is our chance to +synchronize and stabilize our distribution as a whole. Therefore, +care must be taken when uploading to <em/frozen/. + <p> +It is tempting to always try to get the newest release of software +into the release. However, it's much more important that the system +as a whole is stable and works as expected. + <p> +The watchword for uploading to <em/frozen/ is <strong>no new +code</strong>. This is a difficult thing to quantify, so here are +some guidelines: + <p> +<list> + <item> +Fixes for bugs of severity <em/critical/, <em/grave/, or +<em/important/ severity are always allowed for those packages that +must exist in the final release + <item> +<em/critical/, <em/grave/, and <em/important/ bug fixes are only +allowed for non-necessary packages if they don't add any new features + <item> +normal bug fixes are allowed (though discouraged) on all packages if +and only if there are no new features + <item> +wishlist fixes are not allowed (they are, after all, not really bugs) + <item> +documentation bug fixes are allowed, since good documentation is +important + </list> + <p> +Remember, there is statistically a 15% chance that every bug fix will +introduce a new bug. The introduction and discovery of new bugs +either delays release or weakens the final product. There is little +correlation between the severity of the original bug and the severity +of the introduced bug. + - The first time a version is uploaded which corresponds to - a particular upstream version the original source tar file - should be uploaded and included in the <tt/.changes/ file; - subsequent times the very same tar file should be used to - build the new diffs and <tt/.dsc/ files, and it need not - then be uploaded. + + <sect1 id="upload-checking">Checking the package prior to upload <p> +Before you upload your package, you should do basic testing on it. +Make sure you try the following activities (you'll need to have an +older version of the Debian package around). +<list> + <item> +Install the package and make sure the software works, or upgrade the +package from an older version to your new version if a Debian package +for it already exists. + <item> +Run <prgn/lintian/ over the package. You can run <prgn/lintian/ as +follows: <tt>lintian -v <var>package-version</var>.changes</tt>. This will +check the source package as well as the binary package. If you don't +understand the output that <prgn/lintian/ generates, try adding the +<tt/-i/ switch, which will cause <prgn/lintian/ to output a very +verbose description of the problem. + <p> +Normally, a package should <em/not/ be uploaded if it causes lintian +to emit errors (they will start with <tt/E/). + <p> +For more information on <prgn/lintian/, see <ref id="lintian">. + <item> +Downgrade the package to the previous version (if one exists) -- this +tests the <tt/postrm/ and <tt/prerm/ scripts. + <item> +Remove the package, then reinstall it. + </list> + - By default <prgn/dpkg-genchanges/ and - <prgn/dpkg-buildpackage/ will include the original source - tar-file if and only if the Debian revision part of the - source version number is <tt/0/ or <tt/1/, indicating a - new upstream version. This behaviour may be modified by - using <tt/-sa/ to always include it or <tt/-sd/ to always - leave it out. + <sect1 id="upload-master">Uploading to <tt/master/ <p> +To upload a package, you need a personal account on +<ftpsite>master.debian.org</ftpsite>. All maintainers should already +have this account, see <ref id="servers-master">. You can use either +<prgn/ssh/ or <prgn/ftp/ to transfer the files. In either case, the +files need to be placed into +<ftppath>/home/Debian/ftp/private/project/Incoming</ftppath>. (You +cannot upload to Incoming on master using anonymous FTP -- you must +use your user-name and password.) + <p> +<em/Note:/ Do not upload packages containing software that is +export-controlled by the United States government to <tt/master/, or +to the overseas upload queues on <tt/chiark/ or <tt/erlangen/. This +prohibition covers almost all cryptographic software, and even +sometimes software that contains ``hooks'' to cryptographic software, +such as electronic mail readers that support PGP encryption and +authentication. Uploads of such software should go to <tt/non-us/ +(see below). If you are not sure whether U.S. export controls apply +to your package, post a message to +<email/debian-devel@lists.debian.org/ and ask. + <p> +You may also find the Debian package <package/dupload/ useful when +uploading packages. This handy program is distributed with defaults +for uploading via <prgn/ftp/ to <tt/master/, <tt/chiark/, and +<tt/erlangen/. It can also be configured to use <prgn/ssh/. See +<manref name="dupload" section="1"> and <manref name="dupload" +section="5"> for more information. + - If no original source is included in the upload then the - original source tar-file used by <prgn/dpkg-source/ when - constructing the <tt/.dsc/ file and diff to be uploaded - <em/must/ be byte-for-byte identical with the one already - in the archive. If there is some reason why this is not - the case then the new version of the original source - should be uploaded, possibly by using the <tt/-sa/ flag. + <sect1>Uploads via <tt/chiark/ + <p> +If you have a slow network connection to <tt/master/, there are +alternatives. One is to upload files to <tt/Incoming/ via a +upload queue in Europe on <tt/chiark/. For details connect +to <ftpsite>ftp.chiark.greenend.org.uk</ftpsite> using anonymous FTP +and read +<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>. + <p> +<em/Note:/ Do not upload packages containing software that is +export-controlled by the United States government to the queue on +<tt/chiark/. Since this upload queue goes to <tt/master/, the +prescription found in <ref id="upload-master"> applies here as well. <p> +The program <tt/dupload/ supports uploads to <tt/chiark/; please refer +to the documentation that comes with the program for details. - <sect1>Transferring the files to master + + <sect1>Uploads via <tt/erlangen/ + <p> +Another upload queue is available in Germany: just upload +the files via anonymous FTP to <url +id="ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue">. + <p> +The upload must be a complete Debian upload, as you would put it into +<tt/master/'s <tt/Incoming/, i.e., a <tt/.changes/ files along with the +other files mentioned in the <tt/.changes/. The queue daemon also +checks that the <tt/.changes/ is correctly PGP-signed by a Debian +developer, so that no bogus files can find their way to <tt/master/ +via the queue. Please also make sure that the <tt/Maintainer/ field +in the <tt/.changes/ contains <em/your/ e-mail address. The address +found there is used for all replies, just as on <tt/master/. <p> - To upload a package, you need a personal account on the - master server. Just log in via ftp and transfer the - files to - `<tt>/home/Debian/ftp/private/project/Incoming</tt>.' - (You cannot upload to Incoming on master using anonymous - FTP--you must use your user-name and password.) +There's no need to move your files into a second directory after the +upload as on <tt/chiark/. And, in any case, you should get some mail +reply from the queue daemon what happened to your upload. Hopefully it +should have been moved to <tt/master/, but in case of errors you're +notified, too. <p> - You may also find the Debian package '<tt>dupload</tt>' - useful in uploading new packages to master. See the - '<tt>dupload</tt>' documentation for more information. +<em/Note:/ Do not upload packages containing software that is +export-controlled by the United States government to the queue on +<tt/erlangen/. Since this upload queue goes to <tt/master/, the +prescription found in <ref id="upload-master"> applies here as well. <p> +The program <prgn/dupload/ supports uploads to <tt/erlangen/; please refer +to the documentation that comes with the program for details. - <sect1>Uploads via Chiark + + <sect1>Uploading to the non-us server <p> - If you have a slow network connection to the master - system, there are two alternatives: You can upload files - to Incoming via a cron-driven upload queue in Europe on - ftp.chiark.greenend.org.uk. For details connect to chiark - using anonymous FTP and read - <tt>/pub/debian/private/project/README.how-to-upload</tt>. +To upload a package to the <em/non-us/ server you just have to +transfer the files via anonymous ftp to <url +id="ftp://non-us.debian.org/pub/debian-non-US/Incoming">. Note, that +the <tt>.changes</tt> file must have a valid PGP signature from one of +the keys of the developers key-ring. + + + <sect id="upload-announce">Announcing package uploads + <p> +When a package is uploaded an announcement should be posted to one of +the ``debian-changes'' lists. The announcement should give the (source) +package name and version number, and a very short summary of the +changes, in the <em/Subject/ field, and should contain the PGP-signed +<tt/.changes/ file. Some additional explanatory text may be added +before the start of the <tt/.changes/ file. + <p> +If a package is released with the <tt/Distribution:/ set to +`stable', the announcement is sent to +<email/debian-changes@lists.debian.org/. If a package is released +with <tt/Distribution:/ set to `unstable', `experimental', or +`frozen' (when present), the announcement should be posted to +<email/debian-devel-changes@lists.debian.org/ instead. + <p> +On occasion, it is necessary to upload a package to both the +<em/stable/ and <em/unstable/ distributions; this is done by putting +both distributions in the <tt/Distribution:/ line. In such a case the +upload announcement should go to both of the above mailing lists. + <p> +The <prgn/dupload/ program is clever enough to determine for itself +where the announcement should go, and will automatically mail the +announcement to the right list. See <ref id="dupload">. + + <sect id="upload-notification">Notification that a new package has been installed + <p> +The Debian archive maintainers are responsible for handling package +uploads. For the most part, uploads are automatically handled on a +daily basis by an archive maintenance tool called <prgn/dinstall/. +Specifically, updates to existing packages to the `unstable' +distribution are handled automatically. In other cases, notably new +packages, placing the uploaded package into the distribution is +handled manually. When uploads are handled manually, the change to the +archive may take up to a week to occur (please be patient). + <p> +In any case, you will receive notification indicating that the package +has been uploaded via email. Please examine this notification +carefully. You may notice that the package didn't go into the section +you thought you set it to go into. Read on for why. + + <sect1 id="override-file">The override file <p> - The program <tt/dupload/ support uploads to chiark, please - refer to the documentation that comes with the program, - for details. +The <file>debian/control</file> file's <tt/Section/ and <tt/Priority/ +fields do not actually specify where the file will be placed in the +archive, nor its priority. In order to retain the overall integrity +of the archive, it is the archive maintainers who have control over +these fields. The values in the <file>debian/control</file> file are +actually just hints. <p> +The archive maintainers keep track of the canonical sections and +priorities for packages in the <em/override file/. Sometimes the +<em/override file/ needs correcting. Simply changing the package's +<file>control</file> file is not going to work. Instead, you should email +<email/override-change@debian.org/ or submit a bug against +<package/ftp.debian.org/. + <p> +For more information about <em/override files/, see +<manref name="dpkg-scanpackages" section="8"/>, +<file>/usr/doc/debian/bug-log-mailserver.txt</file>, and +<file>/usr/doc/debian/bug-maint-info.txt</file>. + + + + <chapt id="nmu">Non-Maintainer Uploads (NMUs) + <p> +Under certain circumstances it is necessary for someone other than the +official package maintainer to make a release of a package. This is +called a non-maintainer upload, or NMU. + <p> +Debian porters, who compile packages for different architectures, do +NMUs as part of their normal porting activity (see <ref +id="porting">). Another reason why NMUs are done is when a Debian +developers needs to fix another developers' packages in order to +address serious security problems or crippling bugs, especially during +the freeze, or when the package maintainer is unable to release a fix +in a timely fashion. + <p> +This chapter contains information providing guidelines for when and +how NMUs should be done. A fundamental distinction is made between +source and binary NMUs, which is explained in the next section. + + <sect id="nmu-terms">Terminology + <p> +There are two new terms used throughout this section: ``binary NMU'' +and ``source NMU''. These terms are used with specific technical +meaning throughout this document. Both binary and source NMUs are +similar, since they involve an upload of a package by a developer who +is not the official maintainer of that package. That is why it's a +<em/non-maintainer/ upload. + <p> +A source NMU is a upload of a package by a developer who is not the +official maintainer, for the purposes of fixing a bug in the package. +Source NMUs always involves changes to the source (even if it is just +a change to <file>debian/changelog</file>). This can be either a change +to the upstream source, or a change to the Debian bits of the source. + <p> +A binary NMU is a recompilation and upload of a binary package for a +new architecture. As such, it is usually part of a porting effort. A +binary NMU is non-maintainer uploaded binary version of a package +(often for another architecture), with no source changes required. +There are many cases where porters must fix problems in the source in +order to get them to compile for their target architecture; that would +be considered a source NMU rather than a binary NMU. As you can see, +we don't distinguish in terminology between porter NMUs and non-porter +NMUs. + <p> +Both classes of NMUs, source and binary, can be lumped by the term +``NMU''. However, this often leads to confusion, since most people +think ``source NMU'' when they think ``NMU''. So it's best to be +careful. In this chapter, if I use the unqualified term ``NMU'', I +mean both source and binary NMUs. + + + <sect id="nmu-who">Who can do an NMU + <p> +Only official, registered Debian maintainers can do binary or source +NMUs. An official maintainer is someone who has their key in the +Debian key ring. Non-developers, however, are encouraged to download +the source package and start hacking on it to fix problems; however, +rather than doing an NMU, they should just submit worthwhile patches +to the Bug Tracking System. Maintainers almost always appreciate +quality patches and bug reports. + + + <sect id="nmu-when">When to do a source NMU + <p> +Guidelines for when to do a source NMU depend on the target +distribution, i.e., stable, unstable, or frozen. Porters have +slightly different rules than non-porters, due to their unique +circumstances (see <ref id="source-nmu-when-porter">). + <p> +Only critical changes or security bug fixes make it into stable. When +a security bug is detected a fixed package should be uploaded as soon +as possible. In this case, the Debian Security Managers should get in +contact with the package maintainer to make sure a fixed package is +uploaded within a reasonable time (less than 48 hours). If the package +maintainer cannot provide a fixed package fast enough or if he/she +cannot be reached in time, the Security Manager may upload a fixed +package (i.e., do a source NMU). + <p> +During the release freeze (see <ref id="upload-frozen">), NMUs which +fix important or higher severity bugs are encouraged and accepted. +Even during this window, however, you should endeavor to reach the +current maintainer of the package; they might be just about to upload +a fix for the problem. As with any source NMU, the guidelines found +in <ref id="nmu-guidelines"> need to be followed. + <p> +Bug fixes to unstable by non-maintainers are also acceptable, but only +as a last resort or with permission. Try the following steps first, +and if they don't work, it is probably OK to do an NMU: + <p> +<list> + <item> +Make sure that the package bug is in the Debian Bug Tracking System +(BTS). If not, submit a bug. + <item> +Email the maintainer, and offer to help fix the package bug. Give it a +few days. + <item> +Go ahead and fix the bug, submitting a patch to the right bug in the +BTS. Build the package and test it as discussed in <ref +id="upload-checking">. Use it locally. + <item> +Wait a couple of weeks for a response. + <item> +Email the maintainer, asking if it is OK to do an NMU. + <item> +Double check that your patch doesn't have any unexpected side effects. +Make sure your patch is as small and as non-disruptive as it can be. + <item> +Wait another week for a response. + <item> +Go ahead and do the source NMU, as described in <ref +id="nmu-guidelines">. + </list> + + + + <sect id="nmu-guidelines">How to do a source NMU + <p> +The following applies to porters insofar as they are playing the dual +role of being both package bug-fixers and package porters. If a +porter has to change the Debian source archive, automatically their +upload is a source NMU and is subject to its rules. If a porter is +simply uploading a recompiled binary package, the rules are different; +see <ref id="porter-guidelines">. + <p> +First and foremost, it is critical that NMU patches to source should +be as non-disruptive as possible. Do not do housekeeping tasks, do +not change the name of modules or files, do not move directories; in +general, do not fix things which are not broken. Keep the patch as +small as possible. If things bother you aesthetically, talk to the +Debian maintainer, talk to the upstream maintainer, or submit a bug. +However, aesthetic changes must <em/not/ be made in a non-maintainer +upload. + - <sect1>Uploads via Erlangen + <sect1 id="nmu-version">Source NMU version numbering <p> - Another cron-driven upload queue is available in Germany: - Just upload the files via anonymous FTP to - <tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>. +Whenever you have made a change to a package, no matter how trivial, +the version number needs to change. This enables our packing system +to function. <p> - The upload must be a complete Debian upload, as you would - put it into master's incoming, i.e. a <tt/.changes/ files - along with the other files mentioned in the - <tt/.changes/. The queue daemon also checks that the - <tt/.changes/ is correctly PGP-signed by a Debian - developer, so that no bogus files can find their way to - master via the queue. Please also make sure that the - <tt/Maintainer:/ field in the <tt/.changes/ contains - *your* e-mail address. The address found there is used for - all replies, just as on master. +If you are doing a non-maintainer upload (NMU), you should add a new +minor version number to the <var/debian-revision/ part of the version +number (the portion after the last hyphen). This extra minor number +will start at `1'. For example, consider the package `foo', which is +at version 1.1-3. In the archive, the source package control file +would be <file>foo_1.1-3.dsc</file>. The upstream version is `1.1' and +the Debian revision is `3'. The next NMU would add a new minor number +`.1' to the Debian revision; the new source control file would be +<file>foo_1.1-3.1.dsc</file>. <p> - There's no need to move your files into a second directory - after the upload as on chiark. And, in any case, you - should get some mail reply from the queue daemon what - happened to your upload. Hopefully it should have been - moved to master, but in case of errors you're notified, - too. +The Debian revision minor number is needed to avoid stealing one of +the package maintainer's version numbers, which might disrupt their +work. It also has the benefit of making it visually clear that a +package in the archive was not made by the official maintainer. <p> - The program <tt/dupload/ support uploads to erlangen, - please refer to the documentation that comes with the - program, for details. +If there is no <var/debian-revision/ component in the version number +then one should be created, starting at `0.1'. If it is absolutely +necessary for someone other than the usual maintainer to make a +release based on a new upstream version then the person making the +release should start with the <var/debian-revision/ value `0.1'. The +usual maintainer of a package should start their <var/debian-revision/ +numbering at `1'. Note that if you do this, you'll have to invoke +<prgn>dpkg-buildpackage</prgn> with the <tt/-sa/ switch to force the +build system to pick up the new source package (normally it only looks +for Debian revisions of '0' or '1' -- it's not yet clever enough to +know about `0.1'). <p> +Remember, porters who are simply recompiling a package for a different +architecture do not need to renumber. Porters should use new version +numbers if and only if they actually have to modify the source package +in some way, i.e., if they are doing a source NMU and not a binary +NMU. - <sect1>Uploading to the non-us server + + <sect1 id="nmu-changelog">Source NMUs must have a new changelog entry <p> - To upload a package to the <em/non-us/ server you just - have to transfer the files via anonymous ftp to - <tt>ftp://nonus.debian.org/pub/debian-non-US/Incoming</tt>. - Note, that the <tt>.changes</tt> file must have a valid - PGP signature from one of the keys of the developers - keyring. - <p> - - <sect>Announcing package uploads - <p> - When a package is uploaded an announcement should be posted - to one of the debian-changes lists. The announcement should - give the (source) package name and version number, and a - very short summary of the changes, in the <prgn/Subject/ - field, and should contain the PGP-signed <tt/.changes/ file. - Some additional explanatory text may be added before the - start of the <tt/.changes/ file. - <p> - If a package is released with the <tt/Distribution:/ set to - <tt/stable/, the announcement is sent to - <email/debian-changes@lists.debian.org/. - <p> - If a package is released with <tt/Distribution:/ set to - <tt/unstable/, <tt/experimental/, or <tt/frozen/ (when - present), the announcement should be posted to - <email/debian-devel-changes@lists.debian.org/ instead. - <p> - - <sect>Interim releases - <p> - Under certain circumstances it is necessary for someone - other than the usual package maintainer to make a release of - a package. For example, a porter for another architecture - may have to make some small changes to the source package - and does not wish to wait with uploading their release until - the main maintainer has incorporated the patch, or a serious - security problem may have come to light requiring immediate - attention. - <p> - When a security bug is detected a fixed package should be - uploaded as soon as possible. In this case, the Debian - Security Managers should get in contact with the package - maintainer to make sure a fixed package is uploaded within a - reasonable time (less than 48 hours). If the package - maintainer cannot provide a fixed package fast enough or if - he/she cannot be reached in time, the Security Manager - may upload a fixed package. - <p> - When someone other than the usual maintainer releases a - package they should add a new component to the - <var/debian-revision/ component of the version number--that - is, the portion after the (last) hyphen. This extra - component will start at <tt/1/. This is to avoid `stealing' - one of the usual maintainer's version numbers, possibly - disrupting their work. If there is no <var/debian-revision/ - component in the version number then one should be created, - starting at <tt/1/. - <p> - If it is absolutely necessary for someone other than the - usual maintainer to make a release based on a new upstream - version then the person making the release should start with - the <var/debian-revision/ value <tt/0.1/. The usual - maintainer of a package should start their - <var/debian-revision/ numbering at <tt/1/. - <p> - Maintainers other than the usual package maintainer should - make as few changes to the package as possible, and they - should always send a unified context diff (<tt/diff -u/) - detailing their changes to the bug tracking system properly - flagged with the correct package so that the usual - maintainer is kept aware of the situation. If the - non-maintainer upload fixes some bugs, the bug reports - should not be closed. However, the person making the - non-maintainer release should send a short message to the - bug tracking system to all the fixed bugs explaining that - they have been fixed. This way, the maintainer and other - people will get notified about that. - <p> - The normal maintainer should do at least one of - <list compact> - <item> apply the diff, +A non-maintainer doing a source NMU must create a changelog entry, +describing which bugs are fixed by the NMU, and generally why the NMU +was required and what it fixed. The changelog entry will have the +non-maintainer's email address in the log entry and the NMU version +number in it. + <p> +By convention, source NMU changelog entries start with the line +<example> + * Non-maintainer upload +</example> - <item> read the diff and decide on each part of it - themselves, or - <item> if the maintainer decides not to apply the patch - but to release a new version, read the description of the - changes to the next upstream version and ensure that they - fix each problem that was fixed in the non-maintainer - release. - </list> - <p> - In addition, the normal maintainer should <em/always/ - include an entry in the changelog file documenting the - non-maintainer upload. - <p> + <sect1 id="nmu-patch">Source NMUs and the Bug Tracking System + <p> +Maintainers other than the official package maintainer should make as +few changes to the package as possible, and they should always send a +patch as a unified context diff (<tt/diff -u/) detailing their +changes to the Bug Tracking System. + <p> +What if you are simply recompiling the package? In this case, the +process is different for porters than it is for non-porters, as +mentioned above. If you are not a porter and are doing an NMU that +simply requires a recompile (i.e., a new shared library is available +to be linked against, a bug was fixed in <package/debhelper/), there +must still be a changelog entry; therefore, there will be a patch. If +you are a porter, you are probably just doing a binary NMU. (Note: +this leaves out in the cold porters who have to do recompiles -- chalk +it up as a weakness in how we maintain our archive.) + <p> +If the source NMU (non-maintainer upload) fixes some existing bugs, +the bugs in the Bug Tracking System which are fixed need to be +<em/notified/ but not actually <em/closed/ by the non-maintainer. +Technically, only the official package maintainer or the original bug +submitter are allowed to close bugs. However, the person making the +non-maintainer release must send a short message to the relevant bugs +explaining that the bugs have been +fixed by the NMU. Using <email/control@bugs.debian.org/, the party +doing the NMU should also set the severity of the bugs fixed in the +NMU to `fixed'. This ensures that everyone knows that the bug was +fixed in an NMU; however the bug is left open until the changes in the +NMU are incorporated officially into the package by the official +package maintainer. Also, open a bug with the patches needed to +fix the problem, or make sure that one of the other (already open) bugs +has the patches. + <p> +The normal maintainer will either apply the patch or employ an +alternate method of fixing the problem. Sometimes bugs are fixed +independently upstream, which is another good reason to back out an +NMU's patch. If the maintainer decides not to apply the NMU's patch +but to release a new version, the maintainer needs to ensure that the +new upstream version really fixes each problem that was fixed in the +non-maintainer release. + <p> +In addition, the normal maintainer should <em/always/ retain the entry +in the changelog file documenting the non-maintainer upload. + - <sect>Maintainer changes + <sect1 id="nmu-build">Building source NMUs + <p> +Source NMU packages are built normally. Pick a distribution using the +same rules as found in <ref id="upload-dist">. Just as described in +<ref id="uploading">, a normal changes file, etc., will be built. In +fact, all the prescriptions from <ref id="upload"> apply, including +the need to announce the NMU to the proper lists. + <p> +Make sure you do <em/not/ change the value of the maintainer in the +<file>debian/control</file> file. Your name from the NMU entry of the +<file>debian/changelog</file> file will be used for signing the changes +file. + + + + + <chapt id="porting">Porting and Being Ported + <p> +Debian supports an ever-increasing number of architectures. Even if +you are not a porter, and you don't use any architecture but one, it +is part of your duty as a maintainer to be aware of issues of +portability. Therefore, even if you are not a porter, you should read +most of this chapter. + <p> +Porting is the act of building Debian packages for architectures which +is different from the original architecture of the package +maintainer's binary package. It is a unique and essential activity. +In fact, porters do most of the actual compiling of Debian packages. +For instance, for one <em>i386</em> binary package, there has to be a +recompile for each architecture, which is around five more builds. + + + <sect id="kind-to-porters">Being Kind to Porters + <p> +Porters have a difficult and unique task, since they are required to +deal with a large volume of packages. Ideally, every source package +should build right out of the box; unfortunately, this is often not +the case. This section contains a checklist of ``gotchas'' often +committed by Debian maintainers -- common problems which often stymie +porters, and make their jobs unnecessarily more difficult. + <p> +The first and most important watchword is to respond quickly to bug or +issues raised by porters. Please treat porters with courtesy, as if +they were in fact co-maintainers of your package (which in a way, they +are). + <p> +By far, most of the problems encountered by porters are caused by +<em>packaging bugs</em> in the source packages. Here is a checklist +of things you should check or be aware of. + +<enumlist> + <item> +Don't set architecture to a value other than ``all'' or ``any'' unless +you really mean it. In too many cases, maintainers don't follow the +instructions in the <url +id="http://www.debian.org/doc/packaging-manuals/packaging.html/" +name="Debian Packaging Manual">. Setting your architecture to ``i386'' +is usually incorrect. + <item> +Make sure your source package is correct. Do <tt>dpkg-source -x +<var>package</var>.dsc</tt> to make sure your source package unpacks +properly. Then, in there, try building your package from scratch with +<tt>dpkg-buildpackage</tt>. + <item> +Make sure you don't ship your source package with the +<file>debian/files</file> or <file>debian/substvars</file> files. +They should be removed by the `clean' target of +<file>debian/rules</file>. + <item> +Make sure you don't rely on locally installed or hacked configurations +or programs. For instance, you should never be calling programs in +<file>/usr/local/bin</file> or the like. Try not to rely on programs +be setup in a special way. Try building your package on another +machine, even if it's the same architecture. + <item> +Don't depend on the package your building already being installed (a +sub-case of the above issue). + <item> +Don't rely on <prgn>egcc</prgn> being available; don't rely on +<prgn>gcc</prgn> being a certain version. + <item> +Make sure your debian/rules contains separate ``binary-arch'' and +``binary-indep'' targets, as the Debian Packaging Manual requires. +Make sure that both targets work independently, that is, that you can +call the target without having called the other before. To test this, +try to run <tt>dpkg-buildpackage -b</tt>. + </enumlist> + + + <sect id="porter-guidelines">Guidelines for Porter Uploads + <p> +If the package builds out of the box for the architecture to be ported +to, you are in luck and your job is easy. This section applies to +that case; it describes how to build and upload your binary NMU so +that it is properly installed into the archive. If you do have to +patch the package in order to get it to compile for the other +architecture, you are actually doing a source NMU, so consult <ref +id="nmu-guidelines"> instead. + <p> +In a binary NMU, no real changes are being made to the source. You do +not need to touch any of the files in the source package. This +includes <file>debian/changelog</file>. + <p> +The way to invoke <prgn/dpkg-buildpackage/ is as <tt>dpkg-buildpackage +-B -m<var/porter-email/</tt>. Of course, set <var/porter-email/ to +your email address. This will do a binary-only build of only the +architecture-dependant portions of the package, using the +`binary-arch' target in <file>debian/rules</file>. + + + <sect1 id="source-nmu-when-porter"> + <heading>When to do a source NMU if you are a porter</heading> + <p> +Porters doing a source NMU generally follow the guidelines found in +<ref id="nmu">, just like non-porters. However, it is expected that +the wait cycle for a porter's source NMU is smaller than for a +non-porter, since porters have to cope with a large quantity of +packages. + <p> +Again, the situation varies depending on the distribution they are +uploading to. Crucial fixes (i.e., changes need to get a source +package to compile for a released-targeted architecture) can be +uploaded with <em/no/ waiting period for the `frozen' distribution. + <p> +However, if you are a porter doing an NMU for `unstable', the above +guidelines for porting should be followed, with two variations. +Firstly, the acceptable waiting period -- the time between when the +bug is submitted to the BTS and when it is OK to do an NMU -- is seven +days for porters working on the unstable distribution. This period +can be shortened if the problem is critical and imposes hardship on +the porting effort, at the discretion of the porter group. (Remember, +none of this is Policy, just mutually agreed upon guidelines.) + <p> +Secondly, porters doing source NMUs should make sure that the bug they +submit to the BTS should be of severity `important' or greater. This +ensures that a single source package can be used to compile every +supported Debian architecture by release time. It is very important +that we have one version of the binary and source package for all +architecture in order to comply with many licenses. + <p> +Porters should try to avoid patches which simply kludge around bugs in +the current version of the compile environment, kernel, or libc. +Sometimes such kludges can't be helped. If you have to kludge around +compilers bugs and the like, make sure you <tt>#ifdef</tt> your work +properly; also, document your kludge so that people know to remove it +once the external problems have been fixed. + <p> +Porters may also have an unofficial location where they can put the +results of their work during the waiting period. This helps others +running the port have the benefit of the porter's work, even during +the waiting period. Of course, such locations have no official +blessing or status, so buyer, beware. + + + <sect>Tools for Porters <p> - Periodically, a listing of packages in need of new - maintainers will be sent to the <tt>debian-devel</> - list. This list is also available at - <ftpsite>ftp.debian.org</> in - <ftppath>/debian/doc/package-developer/prospective-packages.html</> - If you wish to take over maintenance of any of those - packages, or if you can no longer maintain the packages you - have, or you simply want to know if any one is working on a - new package, send a message to - <email/override-change@debian.org/. +There are several tools available for the porting effort. This section +contains a brief introduction to these tools; see the package +documentation or references for full information. + + + <sect1 id="quinn-diff"> + <heading><package>quinn-diff</package> + <p> +<package/quinn-diff/ is used to locate the differences from one +architecture to another. For instance, it could tell you which +packages need to be ported for architecture <var/Y/, based on +architecture <var/X/. + + + <sect1 id="buildd"> + <heading><package>buildd</package> + <p> +The <package/buildd/ system is used as a distributed, client-server +build distribution system. It is usually used in conjunction with +<em/auto-builders/, which are ``slave'' hosts which simply check out +and attempt to auto-build packages which need to be ported. There is +also an email interface to the system, which allows porters to ``check +out'' a source package (usually one which cannot yet be autobuilt) and +work on it. + <p> +<package/buildd/ is not yet available as a package; however, most +porting efforts are either using it currently or planning to use it in +the near future. It collects a number of as yet unpackaged components +which are currently very useful and in use continually, such as +<prgn/sbuild/ and <prgn/wanna-build/. + <p> +We are very excited about this system, since it potentially has so +many uses. Independent development groups can use the system for +different sub-flavors of Debian, which may or may not really be of +general interest (for instance, a flavor of Debian built with gcc +bounds checking). It will also enable Debian to recompile entire +distributions quickly. + + + <sect1 id="dpkg-cross"> + <heading><package>dpkg-cross</package> + <p> +<package>dpkg-cross</package> is a tool for installing libraries and +headers for cross-compiling in a way similar to +<package>dpkg</package>. Furthermore, the functionality of +<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is +enhanced to support cross-compiling. + + + + + <chapt id="archive-manip"><heading>Moving, Removing, Renaming, + Adopting, and Orphaning Packages</heading> + <p> +Some archive manipulation operation are not automated in the Debian +upload process. These procedures should be manually followed by +maintainers. This chapter gives guidelines in what to do in these +cases. + + <sect>Moving packages + <p> +Sometimes a package will change either its section or its subsection. +For instance, a package from the `non-free' section might be GPL'd in +a later version; in this case you should consider moving it to `main' +or `contrib' (see the <url +id="http://www.debian.org/doc/debian-policy/" name="Debian Policy +Manual"> for guidelines). + <p> +In this case, it is sufficient to edit the package control information +normally and re-upload the package (see the <url +id="http://www.debian.org/doc/packaging-manuals/packaging.html/" +name="Debian Packaging Manual"> for +details). Carefully examine the installation log sent to you when the +package is installed into the archive. If for some reason the old +location of the package remains, file a bug against +<tt/ftp.debian.org/ asking that the old location be removed. Give +details on what you did, since it might be a <prgn/dinstall/ bug. + + + <sect>Removing packages + <p> +If for some reason you want to completely remove a package (say, if it +is an old compatibility library which is not longer required), you +need to file a bug against <tt/ftp.debian.org/ asking that the +package be removed. Make sure you indicate which distribution the +package should be removed from. + <p> +If in doubt concerning whether a package is disposable, email +<email/debian-devel@lists.debian.org/ asking for opinions. Also of +interest is the <prgn/apt-cache/ program from the <package/apt/ +package. When invoked as <tt>apt-cache showpkg +/var/cache/apt/pkgcache.bin <var/package/</tt>, the program will show +details for <var/package/, including reverse depends. + + <sect1>Removing packages from <tt/Incoming/ + <p> +If you decide to remove a package from <tt/Incoming/, it is nice but +not required to send a notification of that to the appropriate +announce list (either <email/debian-changes@lists.debian.org/ or +<email/debian-devel-changes@lists.debian.org/). + + <sect>Replacing or renaming packages + <p> +Sometimes you made a mistake naming the package and you need to rename +it. In this case, you need to follow a two-step process. First, set +your <file>debian/control</file> file to replace and conflict with the +obsolete name of the package (see the <url +id="http://www.debian.org/doc/packaging-manuals/packaging.html/" +name="Debian Packaging Manual"> for details). Once you've uploaded +that package, and the package has moved into the archive, file a bug +against <tt/ftp.debian.org/ asking to remove the package with the +obsolete name. + + + + <sect id="orphaning">Orphaning a package + <p> +If you can no longer maintain a package, then you should set the +package maintainer to <tt>Debian QA Group +<debian-qa@lists.debian.org></tt> and email +<email/wnpp@debian.org/ indicating that the package is now orphaned. +If the package is especially crucial to Debian, you should instead +email <email/debian-devel@lists.debian.org/ asking for a new +maintainer. + + + <sect id="adopting">Adopting a package + <p> +Periodically, a listing of packages in need of new maintainers will be +sent to <email/debian-devel@lists.debian.org</email> list. This list +is also available at in the Work-Needing and Prospective Packages +document (WNPP), <url +id="ftp://ftp.debian.org/debian/doc/package-developer/prospective-packages.html"> +and at <url id="http://www.debian.org/doc/prospective-packages.html">. +If you wish to take over maintenance of any of the packages listed in +the WNPP, or if you can no longer maintain a packages you have, or you +simply want to know if any one is working on a new package, send a +message to <email/wnpp@debian.org/. + <p> +It is not OK to simply take over a package that you feel is neglected +-- that would be package hijacking. You can, of course, contact the +current maintainer and ask them if you may take over the package. +However, without their assent, you may not take over the package. +Even if they ignore you, that is still not grounds to take over a +package. If you really feel that a maintainer has gone AWOL (absent +without leave), post a query to +<email/debian-private@lists.debian.org/. + <p> +If you take over an old package, you probably want to be listed as the +package's official maintainer in the bug system. This will happen +automatically once you upload a new version with an updated +<tt/Maintainer:/ field, although it can take a couple of weeks. If you +do not expect to upload a new version for a while, send an email to +<email/override-change@debian.org/ so that bug reports will go to you +right away. + + + + + <chapt id="bug-handling">Handling Bugs + + <sect>Monitoring bugs + <p> +If you want to be a good maintainer, you should periodically check the +<url id="http://www.debian.org/Bugs/" name="Debian bug tracking system +(BTS)"> for your packages. The BTS contains all the open bugs against +your packages. + <p> +Maintainers interact with the BTS via email addresses at +<tt/bugs.debian.org/. Documentation on available commands can be +found at <url id="http://www.debian.org/Bugs/">, or, if you have +installed the <package/debian-doc/ package, you can look at the local +files <file>/usr/doc/debian/bug-*</file>. + <p> +Some find it useful to get periodic reports on open bugs. You can add +a cron job such as the following if you want to get a weekly email +outlining all the open bugs against your packages: +<example> +# ask for weekly reports of bugs in my packages +0 17 * * fri echo "index maint <var>maintainer-address</var>" | mail request@bugs.debian.org +</example> +Replace <var>maintainer-address</var> with you official Debian +maintainer address. + + <sect id="submit-bug">Submitting Bugs + <p> +Often as a package maintainer, you find bugs in other packages or else +have bugs reported to your packages which need to be reassigned. The +BTS <url id="http://www.debian.org/Bugs/server-control.html" +name="instructions"> can tell you how to do this. + <p> +We encourage you to file bugs when there are problems. Try to submit +the bug from a normal user account at which you are likely to receive +mail. Do not submit bugs as root. + <p> +Make sure the bug is not already filed against a package. Try to do a +good job reporting a bug and redirecting it to the proper location. +For extra credit, you can go through other packages, merging bugs +which are reported more than once, or setting bug severities to +`fixed' when they have already been fixed. Note that when you are +neither the bug submitter nor the package maintainer, you are should +not actually close the bug (unless you secure permission from the +maintainer). + + <sect>Responding to Bugs <p> - If you take over an old package, you probably want to be - listed as the package's official maintainer in the bug - system. This will happen automatically once you upload a new - version with an updated <tt/Maintainer:/ field. If you do - not expect to upload a new version for a while, send an - email to <email/override-change@debian.org/ so that bug - reports will go to you. +Make sure that any discussions you have about bugs are sent both to +the original submitter of the bug, and the bug itself (i.e., +<email>123@bugs.debian.org</email>). <p> +You should <em>never</em> close bugs via the bug server `close' +command sent to <email>control@bugs.debian.org</email>. If you do so, +the original submitter will not receive any feedback on why the bug +was closed. + + <sect>When bugs are closed by new uploads + <p> +If you fix a bug in your packages, it is your responsibility as the +package maintainer to close the bug when it has been fixed. However, +you should not close the bug until the package which fixes the bug has +been accepted into the Debian archive. Therefore, once you get +notification that your updated package has been installed into the +archive, you can and should close the bug in the BTS. + <p> +Again, see the BTS documentation for details on how to do this. +Often, it is sufficient to mail the <tt/.changes file to +<email/<var/XXX/-done@bugs.debian.org/, where <var/XXX/ is your bug +number. + + + <sect id="lintian-reports">Lintian reports + <p> +You should periodically get the new <package/lintian/ from `unstable' and +check over all your packages. Alternatively you can check for your +maintainer email address at the <url +id="http://www.debian.org/lintian/" name="online lintian report">. +That report, which is updated automatically, contains <prgn/lintian/ +reports against the latest version of the distribution (usually from +'unstable') using the latest <package/lintian/. - <chapt>Handling bug reports<p> <sect>Reporting lots of bugs at once <p> - If you report more then 10 bugs on the same topic at once, - it is recommended that you send a message to debian-devel - describing your intention before submitting the report. This - will allow other developers to verify that the bug is a real - problem. In addition, it will prevent the situation where - several maintainers start filing the same bug report - simultaneously. - <p> - Note, that when sending lots of bugs on the same subject, - you should send the bug report to - <tt/maintonly@bugs.debian.org/ so that the bug report is not - forwarded to the bug distribution mailing list. - <p> - -</book> +Reporting a great number of bugs for the same problem on a great +number of different packages -- i.e., more than 10 -- is a deprecated +practice. Take all possible steps to avoid submitting bulk bugs at +all. For instance, if checking for the problem can be automated, add +a new check to <package/lintian/ so that an error or warning is +emitted. + <p> +If you report more than 10 bugs on the same topic at once, it is +recommended that you send a message to +<email/debian-devel@lists.debian.org/ describing your intention before +submitting the report. This will allow other developers to verify that +the bug is a real problem. In addition, it will help prevent a +situation in which several maintainers start filing the same bug +report simultaneously. + <p> +Note that when sending lots of bugs on the same subject, you should +send the bug report to <email/maintonly@bugs.debian.org/ so that the +bug report is not forwarded to the bug distribution mailing list. + + + <chapt id="tools">Overview of Debian Maintainer Tools + <p> +This section contains a rough overview of the tools available to +maintainers. These tools are meant to help convenience developers and +free their time for critical tasks. + <p> +Some people prefer to use high-level package maintenance tools and +some do not. Debian is officially agnostic on this issue; any tool +which gets the job done is fine. Therefore, this section is not meant +to stipulate to anyone which tools they should use or how they should +go about with their duties of maintainership. Nor is it meant to +endorse any particular tool to the exclusion of a competing tool. + <p> +Most of the descriptions of these packages come from the actual +package descriptions themselves. Further information can be found in +the package documentation itself. + + + <sect id="dpkg-dev"> + <heading><package/dpkg-dev/ + <p> +<package/dpkg-dev/ contains the tools (including +<prgn/dpkg-source/) required to unpack, build and upload Debian source +packages. These utilities contain the fundamental, low-level +functionality required to create and manipulated packages; as such, +they are required for any Debian maintainer. + + + <sect id="lintian"> + <heading><package/lintian/ + <p> +<package/Lintian/ dissects Debian packages and reports bugs and +policy violations. It contains automated checks for many aspects of +Debian policy as well as some checks for common errors. The use of +<package/lintian/ has already been discussed in <ref +id="upload-checking"> and <ref id="lintian-reports">. + + + <sect id="debhelper"> + <heading><package/debhelper/ + <p> +<package/debhelper/ is a collection of programs that can be used in +<file>debian/rules</file> to automate common tasks related to building +binary Debian packages. Programs are included to install various files +into your package, compress files, fix file permissions, integrate +your package with the Debian menu system. + <p> +Unlike <package/debmake/, <package/debhelper/ is broken into +several small, granular commands which act in a consistent manner. As +such, it allows a greater granularity of control than +<package/debmake/. + + + <sect id="debmake"> + <heading><package/debmake/ + <p> +<package/debmake/, a pre-cursor to <package/debhelper/, is a +less granular <file>debian/rules</file> assistant. It includes two main +programs: <prgn>deb-make</prgn>, which can be used to help a +maintainer convert a regular (non-Debian) source archive into a Debian +source package; and <prgn>debstd</prgn>, which incorporates in one big +shot the same sort of automated functions that one finds in +<package/debhelper/. + <p> +The consensus is that <package>debmake</package> is now deprecated in +favor of <package>debhelper</package>. However, it's not a bug to use +<package>debmake</package>. + + + <sect id="cvs-buildpackage"> + <heading><package/cvs-buildpackage/ + <p> +<package/cvs-buildpackage/ provides the capability to inject or +import Debian source packages into a CVS repository, build a Debian +package from the CVS repository, and helps in integrating upstream +changes into the repository. + <p> +These utilities provide an infrastructure to facilitate the use of CVS +by Debian maintainers. This allows one to keep separate CVS branches +of a package for <em/stable/, <em/unstable/, and possibly +<em/experimental/ distributions, along with the other benefits of a +version control system. + + + <sect id="dupload"> + <heading><package>dupload</package> + <p> +<package/dupload/ is a package and a script to automagically upload +Debian packages to the Debian archive, to log the upload, and to send +mail about the upload of a package. You can configure it for new +upload locations or methods. + + + <sect id="fakeroot"> + <heading><package>fakeroot</package> + <p> +<package>fakeroot</package> simulates root privileges. This enables +you to build packages without being root (packages usually want to +install files with root ownership). If you have +<package>fakeroot</package> installed, you can say, i.e., +<tt>dpkg-buildpackage -rfakeroot</tt> as a user. + + + <sect id="devscripts"> + <heading><package>devscripts</package> + <p> +<package>devscripts</package> is a package containing a few wrappers +and tools which you may find helpful for maintaining your Debian +packages. Example scripts include <prgn>debchange</prgn>, which will +manipulate your <file>debian/changelog</file> file from the +command-line, and <prgn>build</prgn>, which is a wrapper around +<prgn>dpkg-buildpackage</prgn>. + + + <sect id="debget"> + <heading><package>debget</package> + <p> +<package>debget</package> is a package containing a convenient script +which can be helpful in downloading files from the Debian archive. +You can use it to download source packages, for instance. + + + </book> +</debiandoc> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:nil +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-declaration:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +-->