X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=blobdiff_plain;f=developers-reference.sgml;h=13f2368ce266b9117e079a85b9742f60af4b0170;hp=9b73ed21b33e7cf2af94e0025861a9ab2c9fabc3;hb=51521555be3ad4f8da4c287ce6afd155a588315c;hpb=ebf8a16bd52ebaeb992c7f6af08c77f90900c51e diff --git a/developers-reference.sgml b/developers-reference.sgml index 9b73ed2..13f2368 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,758 +1,1949 @@ - + + %versiondata; + + %commondata; + + + + +]> + - - - - -Debian Developer's Reference -<author>Christian Schwarz <email/schwarz@debian.org/ -<author>based on earlier documents by Ian Jackson <email/ijackson@gnu.ai.mit.edu/ -<version>version 2.4.1.2, 14 April 1998 + <book> -<copyright>Copyright ©1997,1998 Christian Schwarz. -<p> + <title>Debian Developer's Reference + <author>Adam Di Carlo, current maintainer <email>aph@debian.org</email> + <author>Christian Schwarz <email>schwarz@debian.org</email> + <author>Ian Jackson <email>ijackson@gnu.ai.mit.edu</email> + <version>ver. &version;, &date; + <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 &fsf-addr;. - <toc sect> + <toc detail="sect2"> - <chapt>Applying to Become a Maintainer<p> + <chapt id="scope">Scope of This Document + <p> +The purpose of this document is to provide an overview of the +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="&url-pkg-manual;" +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="&url-debian-policy;" name="Debian Policy +Manual">. + <p> +Furthermore, this document is <em>not an expression of formal +policy</em>. It contains documentation for the Debian system, and +generally agreed-upon best practices. + + + <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</package> example package is for, and you're about to +Debianize your favourite piece of software. How do you actually +become a Debian developer so that your work can be incorporated into +the Project? + <p> +Firstly, subscribe to <email>debian-devel@lists.debian.org</email> if +you haven't already. Send the word <tt>subscribe</tt> in the +<em>Subject</em> of an email to +<email>debian-devel-REQUEST@lists.debian.org</email>. In case of +problems, contact the list administrator at +<email>listmaster@lists.debian.org</email>. 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</email>. See <ref +id="mentors"> for details. The IRC channel <tt>#debian</tt> on the +Linux People IRC network (i.e., <tt>irc.debian.org</tt>) 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="&url-social-contract;" name="Debian Social +Contract">. Registering as a developer means that you agree with and +pledge to uphold the Debian Social Contract; it is very important that +maintainers are in accord with the essential ideas behind Debian +GNU/Linux. Reading the <url id="&url-gnu-manifesto;" name="GNU +Manifesto"> would also be a good idea. + <p> +The process of registering as a developer is a process of verifying +your identity and intentions. 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</email> as part of the registration +application: +<list> + <item> +Your name. + <item> +Your preferred login name on <tt>master</tt> (eight characters or +less), as well as the email address at which you'd prefer to be +subscribed to <email>debian-private@lists.debian.org</email> +(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</em>. + <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</prgn> version 5, if and only if you make an RSA key. Note +that we are also working with the <prgn>gpg</prgn> 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 +&pgp-keyserv;, 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</ftpsite> or +<ftpsite>ftp.us.debian.org</ftpsite> 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</em> cryptography in any manner. If you live in a +country where use of cryptography even for authentication is forbidden +then please contact us so we can make special arrangements. + <p> +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</email> 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</ftpsite> in +<ftppath>/pub/debian/doc/debian-keyring.tar.gz</ftppath>, or the +<package>debian-keyring</package> 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</em> 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</email> +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>The FTP servers - <p> + <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 WWW servers - <p> - <chapt>The Debian Archive<p> - - <sect>Overview - <p> + <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. - 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 + <sect id="mailing-lists">Mailing lists + <p> +The mailing list server is at <tt>lists.debian.org</tt>. Mail +<tt>debian-<var>foo</var>-REQUEST@lists.debian.org</tt>, where +<tt>debian-<var>foo</var></tt> is the name of the list, with the word +<tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or +<tt>unsubscribe</tt> to unsubscribe. More detailed instructions on +how to subscribe and unsubscribe to the mailing lists can be found at +<url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;"> +or locally in <file>/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</tt>) to the original poster unless they explicitly +request to be copied. Anyone who posts to a mailing list should read +it to see the responses. + <p> +In addition, all messages should usually only be sent to one of the +following mailing lists: <email>debian-devel@lists.debian.org</email>, +<email>debian-policy@lists.debian.org</email>, +<email>debian-user@lists.debian.org</email>, +<email>debian-announce@lists.debian.org</email>, or +<email>debian-devel-announce@lists.debian.org</email>. Additional +mailing lists are available for special purposes; see <url +id="&url-debian-lists-subscribe;">. Cross-posting +(sending the same message to multiple lists) is discouraged. + <p> +<email>debian-private@lists.debian.org</email> 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</email> unless it is +really necessary. Moreover, do <em>not</em> 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="&url-debian-list-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="&url-debian-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</tt>, holds the canonical copy +of the Debian archive (excluding the non-U.S. packages). Generally, +package uploads go to this server; see <ref id="upload">. + <p> +<tt>master.debian.org</tt> is the canonical location for the Bug +Tracking System (BTS). If you plan on doing some statistical analysis +or processing of Debian bugs, this would be the place to do it. +Please describe your plans on +<email>debian-devel@lists.debian.org</email> before implementing +anything, however, to reduce unnecessary duplication of effort or +wasted processing time. + <p> +All Debian developers have accounts on <tt>master.debian.org</tt>. Please +take care to protect your password to this machine. Try to avoid +login or upload methods which send passwords over the Internet in the +clear. + <p> +If you find a problem with <tt>master.debian.org</tt> such as disk full, +suspicious activity, or whatever, send an email to +<email>debian-admin@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</tt>, is also known as +<tt>va.debian.org</tt>. All developers are given accounts on this +machine. + <p> +If you have some Debian-specific information which you want to serve +up on the web, you can do 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</tt> or +<tt>master.debian.org</tt>. 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</tt>, for the +<tt>www.debian.org</tt> address, although in some cases you may need +to put it on <tt>master</tt>. 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</email> +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="&url-bts;db/pa/lwww.debian.org.html" name="Bug Tracking System">. + + + <sect1 id="servers-cvs">The CVS server <p> +<tt>cvs.debian.org</tt> is also known as <tt>va.debian.org</tt>, +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</tt> offers a combination of local CVS +access, anonymous client-server read-only access, and full +client-server access through <prgn>ssh</prgn>. Also, the CVS area can +be accessed read-only via the Web at <url +id="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="&url-debian-mirrors">. More information +concerning Debian mirrors can be found at <url +id="&url-debian-mirroring">. This useful page includes +information and tools which can be helpful if you are interested in +setting up your own mirror, either for internal or public access. + <p> +Note that mirrors are generally run by third-parties who are +interested in helping Debian. As such, developers generally do not +have accounts on these machines. + <p> +Please do not mirror off of <tt>master.debian.org</tt>. This host +already has too much load. Check the sites above for information, or +email <email>debian-devel@lists.debian.org</email>. + + + <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. - 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. + <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 + + <sect>Overview <p> - For example, every package in the main distribution must - fully comply with the <em>Debian Free Software Guidelines</> - (DFSG) and with all other policy requirements as described - in the <em>Debian Policy Manual</em>. (The DFSG is our - definition of ``free software.'' Check out the Debian Policy - Manual for details.) +The Debian GNU/Linux distribution consists of a lot of Debian packages +(<tt>.deb</tt>'s, currently around &number-of-pkgs;) and a few +additional files (documentation, installation disk images, etc.). <p> - The packages which do not apply to the DFSG are placed in - the <em>non-free</> section. These packages are not - considered as part of the Debian distribution, though we - support their use, and we provide infrastructure (such as - our bug-tracking system and mailing lists) for non-free - software packages. +Here is an example directory tree of a complete Debian distribution: <p> - Packages in the <em>contrib</> section have to apply to - the DFSG, but fail other requirements. +&sample-dist-dirtree; <p> - (The Debian Policy Manual contains a more exact definition - of the three sections. This is just meant to be an - introduction.) +As you can see, the top-level directory of the distribution contains +three directories, namely <em>main</em>, <em>contrib</em>, and +<em>non-free</em>. These directories are called <em>sections</em>. <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. +In each section, there is a directory with the source packages +(source), a directory for each supported architecture +(<tt>binary-i386</tt>, <tt>binary-m68k</tt>, etc.), and a directory +for architecture independent packages (<tt>binary-all</tt>). <p> - 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.) +The <em>main</em> 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>, <tt>disks-m68k</tt>, etc.). <p> +The <em>binary</em> and <em>source</em> directories are divided +further into <em>subsections</em>. - <sect>Architectures - <p> - In the first days, the Linux kernel was only available for - the Intel i386 (or greater) platforms, and so was - Debian. But when Linux became more and more popular, the - kernel was ported to other architectures, too. - <p> - The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, - M68000 machines (like Atari and Amiga), MIPS, and - PowerPC. - <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. + <sect>Sections <p> +The <em>main</em> section is what makes up the <em>official Debian +GNU/Linux distribution</em>. The <em>main</em> section is official +because it fully complies with all our guidelines. The other two +sections do not, to different degrees; as such, they are not +officially part of Debian. + <p> +Every package in the main section must fully comply with the <url +id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and +with all other policy requirements as described in the <url +id="&url-debian-policy;" name="Debian Policy Manual">. The DFSG is +our definition of ``free software.'' Check out the Debian Policy +Manual for details. + <p> +The packages which do not apply to the DFSG are placed in the +<em>non-free</em> section. These packages are not considered as part +of the Debian distribution, though we support their use, and we +provide infrastructure (such as our bug-tracking system and mailing +lists) for non-free software packages. + <p> +Packages in the <em>contrib</em> section have to comply with the DFSG, +but may fail other requirements. For instance, they may depend on +non-free packages. + <p> +The <url id="&url-debian-policy;" name="Debian Policy Manual"> +contains a more exact definition of the three sections. The above +discussion is just an introduction. + <p> +The separation of the three sections at the top-level of the archive +is important for all people who want to distribute Debian, either via +FTP servers on the Internet or on CD-ROMs: by distributing only the +<em>main</em> and <em>contrib</em> sections, one can avoid any legal +risks. Some packages in the <em>non-free</em> section do not allow +commercial distribution, for example. + <p> +On the other hand, a CD-ROM vendor could easily check the individual +package licenses of the packages in <em>non-free</em> and include as +many on the CD-ROMs as he's allowed. (Since this varies greatly from +vendor to vendor, this job can't be done by the Debian developers.) - <sect>Sub sections + + <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. - 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> +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>Subsections + <p> +The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em> +are split into <em>subsections</em> to simplify the installation +process and the maintainance of the archive. Subsections are not +formally defined, 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</em> and +<em>binary</em> packages. + <p> +Source packages consist of either two or three files: a <tt>.dsc</tt> +file, and either a <tt>.tar.gz</tt> file or both an +<tt>.orig.tar.gz</tt> and a <tt>.diff.gz</tt> file. + <p> +If a package is developed specially for Debian and is not distributed +outside of Debian, there is just one <tt>.tar.gz</tt> file which +contains the sources of the program. If a package is distributed +elsewhere too, the <tt>.orig.tar.gz</tt> file stores the so-called +<em>upstream source code</em>, that is the source code that's +distributed from the <em>upstream maintainer</em> (often the author of +the software). In this case, the <tt>.diff.gz</tt> contains the +changes made by the Debian maintainer. + <p> +The <tt>.dsc</tt> lists all the files in the source package together +with checksums (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</em>. Every +distribution is contained in the <tt>dists</tt> 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</tt> 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> - 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> +Extrapolating from this layout, you know that to find the i386 base +packages for the distribution <em>slink</em>, 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</em> (residing in +<tt>dists/stable</tt>) and one called <em>unstable</em> (residing in +<tt>dists/unstable</tt>). This reflects the development process of the +Debian project. + <p> +Active development is done in the <em>unstable</em> distribution +(that's why this distribution is sometimes called the <em>development +distribution</em>). Every Debian developer can update his or her +packages in this distribution at any time. Thus, the contents of this +distribution change from day-to-day. Since no special effort is done +to test this distribution, it is sometimes ``unstable.'' + <p> +After a period of development, the <em>unstable</em> distribution is +copied in a new distribution directory, called <em>frozen</em>. 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</em> distribution is renamed to +<em>stable</em>, overriding the old <em>stable</em> distribution, +which is removed at that time. + <p> +This development cycle is based on the assumption that the +<em>unstable</em> distribution becomes <em>stable</em> after passing a +period of testing as <em>frozen</em>. 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</em> in the <tt>proposed-updates</tt> +directory. Those packages in <tt>proposed-updates</tt> that pass +muster are periodically moved as a batch into the stable distribution +and the revision level of the stable distribution is incremented +(e.g., `1.3' becomes `1.3r1', `2.0r2' becomes `2.0r3', and so forth). + <p> +Note that development under <em>unstable</em> is continued during the +``freeze'' period, since a new <em>unstable</em> distribution is be +created when the older <em>unstable</em> is moved to <em>frozen</em>. +Another wrinkle is that when the <em>frozen</em> distribution is +offically released, the old stable distribution is completely removed +from the Debian archives (although they do live on at +<tt>archive-host;</tt>). + <p> +In summary, there is always a <em>stable</em> and an <em>unstable</em> +distribution available, and the <em>frozen</em> distribution shows up +for a month or so from time to time. + + + <sect1>Experimental + <p> +The <em>experimental</em> 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</em> are expected to have been duly +warned. In short, all bets are off for the <em>experimental</em> +distribution. + <p> +Developers should be very selective in the use of the +<em>experimental</em> distribution. Even if a package is highly +unstable, it could well still go into <em>unstable</em>; 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</em>. + <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. + + + <sect id="codenames">Release code names + <p> +Every released Debian distribution has a <em>code name</em>: Debian +1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0, +`hamm'; Debian 2.1, `slink'; 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</em> and symbolic +links for <em>stable</em>, <em>unstable</em>, and <em>frozen</em> +point to the appropriate release directories. + + + <chapt id="upload">Package uploads <sect>Announcing new packages <p> - If you want to create a new package for the Debian - distribution, you have to send a short email to - <em/debian-devel/ describing your plans before you upload - the new package. - <p> - This has the following advantages: - +If you want to create a new package for the Debian distribution, you +should first check the <url +id="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</email> describing +your plan to create a new package. You should set the subject of the +email to ``intent to package <var>foobar</var>'', substituting the +name of the new package for <var>foobar</var>. + <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</email> +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</tt> 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</tt> file, which gives directions to the +archive maintainers for its handling. This is usually generated by +<prgn>dpkg-genchanges</prgn> during the normal package build process. + <p> +The changes file is a control file with the following fields: + <p> +<list compact> + <item><tt>Format</tt> + <item><tt>Date</tt> + <item><tt>Source</tt> + <item><tt>Binary</tt> + <item><tt>Architecture</tt> + <item><tt>Version</tt> + <item><tt>Distribution</tt> + <item><tt>Urgency</tt> + <item><tt>Maintainer</tt> + <item><tt>Description</tt> + <item><tt>Changes</tt> + <item><tt>Files</tt> + </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</tt> field is discussed here, since it +relates to the archive maintenance policies. + + <sect1 id="upload-dist">Picking a distribution + <p> +Notably, the <tt>Distribution</tt> 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</em> and <em>unstable</em> distributions, then you might +put `stable unstable' in the <file>changelog</file>'s +<tt>Distribution</tt> field. Or, if Debian has been frozen, and you +want to get a bug-fix release into <em>frozen</em>, you would set the +distribution to `frozen unstable'. (See <ref id="upload-frozen"> for +more information on when to upload to <em>frozen</em>.) 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</em>. Also note that it never makes sense to combine the +<em>experimental</em> 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</tt> file; subsequent times the very same +tar file should be used to build the new diffs and <tt>.dsc</tt> +files, and it need not then be uploaded. + <p> +By default <prgn>dpkg-genchanges</prgn> and +<prgn>dpkg-buildpackage</prgn> will include the original source tar +file if and only if the Debian revision part of the source version +number is <tt>0</tt> or <tt>1</tt>, indicating a new upstream version. +This behaviour may be modified by using <tt>-sa</tt> to always include +it or <tt>-sd</tt> to always leave it out. + <p> +If no original source is included in the upload then the original +source tar-file used by <prgn>dpkg-source</prgn> when constructing the +<tt>.dsc</tt> file and diff to be uploaded <em>must</em> be +byte-for-byte identical with the one already in the archive. If there +is some reason why this is not the case then the new version of the +original source should be uploaded, possibly by using the <tt>-sa</tt> +flag. + + <sect2 id="upload-frozen">Uploading to <em>frozen</em> + <p> +The Debian freeze is a crucial time for Debian. It is our chance to +synchronize and stabilize our distribution as a whole. Therefore, +care must be taken when uploading to <em>frozen</em>. + <p> +It is tempting to always try to get the newest release of software +into the release. However, it's much more important that the system +as a whole is stable and works as expected. + <p> +The watchword for uploading to <em>frozen</em> is <strong>no new +code</strong>. This is a difficult thing to quantify, so here are +some guidelines: + <p> +<list> + <item> +Fixes for bugs of severity <em>critical</em>, <em>grave</em>, or +<em>important</em> severity are always allowed for those packages that +must exist in the final release + <item> +<em>critical</em>, <em>grave</em>, and <em>important</em> 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. + - When a package is uploaded to the Debian FTP archive, it - must be accompanied by a <tt/.changes/ file which gives - directions for its handling. This is usually generated by - <prgn/dpkg-genchanges/. - <p> - - This file is a control file with the following fields: - <list compact> - <item><tt/Format/ - <item><tt/Date/ - <item><tt/Source/ - <item><tt/Binary/ - <item><tt/Architecture/ - <item><tt/Version/ - <item><tt/Distribution/ - <item><tt/Urgency/ - <item><tt/Maintainer/ - <item><tt/Description/ - <item><tt/Changes/ - <item><tt/Files/ + + <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</prgn> over the package. You can run +<prgn>lintian</prgn> as follows: <tt>lintian -v +<var>package-version</var>.changes</tt>. This will check the source +package as well as the binary package. If you don't understand the +output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt> +switch, which will cause <prgn>lintian</prgn> to output a very verbose +description of the problem. + <p> +Normally, a package should <em>not</em> be uploaded if it causes lintian +to emit errors (they will start with <tt>E</tt>). + <p> +For more information on <prgn>lintian</prgn>, see <ref id="lintian">. + <item> +Downgrade the package to the previous version (if one exists) -- this +tests the <tt>postrm</tt> and <tt>prerm</tt> scripts. + <item> +Remove the package, then reinstall it. </list> + + + <sect1 id="upload-master">Uploading to <tt>master</tt> + <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</prgn> or <prgn>ftp</prgn> 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:</em> Do not upload packages containing software that is +export-controlled by the United States government to <tt>master</tt>, +or to the overseas upload queues on <tt>chiark</tt> or +<tt>erlangen</tt>. This prohibition covers almost all cryptographic +software, and even sometimes software that contains ``hooks'' to +cryptographic software, such as electronic mail readers that support +PGP encryption and authentication. Uploads of such software should go +to <tt>non-us</tt> (see 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</email> and ask. + <p> +You may also find the Debian package <package>dupload</package> useful +when uploading packages. This handy program is distributed with +defaults for uploading via <prgn>ftp</prgn> to <tt>master</tt>, +<tt>chiark</tt>, and <tt>erlangen</tt>. It can also be configured to +use <prgn>ssh</prgn>. See <manref name="dupload" section="1"> and +<manref name="dupload" section="5"> for more information. + + + <sect1>Uploads via <tt>chiark</tt> + <p> +If you have a slow network connection to <tt>master</tt>, there are +alternatives. One is to upload files to <tt>Incoming</tt> via a +upload queue in Europe on <tt>chiark</tt>. For details connect to +<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:</em> Do not upload packages containing software that is +export-controlled by the United States government to the queue on +<tt>chiark</tt>. Since this upload queue goes to <tt>master</tt>, the +prescription found in <ref id="upload-master"> applies here as well. + <p> +The program <tt>dupload</tt> supports uploads to <tt>chiark</tt>; please refer +to the documentation that comes with the program for details. + + + <sect1>Uploads via <tt>erlangen</tt> <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</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files +along with the other files mentioned in the <tt>.changes</tt>. The +queue daemon also checks that the <tt>.changes</tt> is correctly +PGP-signed by a Debian developer, so that no bogus files can find +their way to <tt>master</tt> via the queue. Please also make sure that +the <tt>Maintainer</tt> field in the <tt>.changes</tt> contains +<em>your</em> e-mail address. The address found there is used for all +replies, just as on <tt>master</tt>. + <p> +There's no need to move your files into a second directory after the +upload as on <tt>chiark</tt>. And, in any case, you should get some +mail reply from the queue daemon what happened to your +upload. Hopefully it should have been moved to <tt>master</tt>, but in +case of errors you're notified, too. + <p> +<em>Note:</em> Do not upload packages containing software that is +export-controlled by the United States government to the queue on +<tt>erlangen</tt>. Since this upload queue goes to <tt>master</tt>, the +prescription found in <ref id="upload-master"> applies here as well. + <p> +The program <prgn>dupload</prgn> supports uploads to +<tt>erlangen</tt>; please refer to the documentation that comes with +the program for details. - 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>Uploading to the non-us server <p> +To upload a package to the <em>non-us</em> 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. + - The first time a version is uploaded which corresponds to - a particular upstream version the original source tar file - should be uploaded and included in the <tt/.changes/ file; - subsequent times the very same tar file should be used to - build the new diffs and <tt/.dsc/ files, and it need not - then be uploaded. + <sect id="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</em> field, and should contain the +PGP-signed <tt>.changes</tt> file. Some additional explanatory text +may be added before the start of the <tt>.changes</tt> file. + <p> +If a package is released with the <tt>Distribution:</tt> set to +`stable', the announcement is sent to +<email>debian-changes@lists.debian.org</email>. If a package is +released with <tt>Distribution:</tt> set to `unstable', +`experimental', or `frozen' (when present), the announcement should be +posted to <email>debian-devel-changes@lists.debian.org</email> +instead. + <p> +On occasion, it is necessary to upload a package to both the +<em>stable</em> and <em>unstable</em> distributions; this is done by +putting both distributions in the <tt>Distribution:</tt> line. In +such a case the upload announcement should go to both of the above +mailing lists. + <p> +The <prgn>dupload</prgn> 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"> + <heading>Notification that a new package has been installed</heading> + <p> +The Debian archive maintainers are responsible for handling package +uploads. For the most part, uploads are automatically handled on a +daily basis by an archive maintenance tool called +<prgn>dinstall</prgn>. Specifically, updates to existing packages to +the `unstable' distribution are handled automatically. In other cases, +notably new packages, placing the uploaded package into the +distribution is handled manually. When uploads are handled manually, +the change to the archive may take up to a 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 <file>debian/control</file> file's <tt>Section</tt> and +<tt>Priority</tt> fields do not actually specify where the file will +be placed in the archive, nor its priority. In order to retain the +overall integrity of the archive, it is the archive maintainers who +have control over these fields. The values in the +<file>debian/control</file> file are actually just hints. + <p> +The archive maintainers keep track of the canonical sections and +priorities for packages in the <em>override file</em>. Sometimes the +<em>override file</em> 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</email> or submit a +bug against <package>ftp.debian.org</package>. <p> +For more information about <em>override files</em>, 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. - 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. + <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</em> 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</em> be made in a non-maintainer +upload. + + + <sect1 id="nmu-version">Source NMU version numbering + <p> +Whenever you have made a change to a package, no matter how trivial, +the version number needs to change. This enables our packing system +to function. + <p> +If you are doing a non-maintainer upload (NMU), you should add a new +minor version number to the <var>debian-revision</var> part of the +version number (the portion after the last hyphen). This extra minor +number will start at `1'. For example, consider the package `foo', +which is at version 1.1-3. In the archive, the source package control +file would be <file>foo_1.1-3.dsc</file>. The upstream version is +`1.1' and the Debian revision is `3'. The next NMU would add a new +minor number `.1' to the Debian revision; the new source control file +would be <file>foo_1.1-3.1.dsc</file>. + <p> +The Debian revision minor number is needed to avoid stealing one of +the package maintainer's version numbers, which might disrupt their +work. It also has the benefit of making it visually clear that a +package in the archive was not made by the official maintainer. <p> +If there is no <var>debian-revision</var> component in the version +number then one should be created, starting at `0.1'. If it is +absolutely necessary for someone other than the usual maintainer to +make a release based on a new upstream version then the person making +the release should start with the <var>debian-revision</var> value +`0.1'. The usual maintainer of a package should start their +<var>debian-revision</var> numbering at `1'. Note that if you do +this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the +<tt>-sa</tt> switch to force the build system to pick up the new +source package (normally it only looks for Debian revisions of '0' or +'1' -- it's not yet clever enough to know about `0.1'). + <p> +Remember, porters who are simply recompiling a package for a different +architecture do not need to renumber. Porters should use new version +numbers if and only if they actually have to modify the source package +in some way, i.e., if they are doing a source NMU and not a binary +NMU. + - 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 id="nmu-changelog"> + <heading>Source NMUs must have a new changelog entry</heading> <p> +A non-maintainer doing a source NMU must create a changelog entry, +describing which bugs are fixed by the NMU, and generally why the NMU +was required and what it fixed. The changelog entry will have the +non-maintainer's email address in the log entry and the NMU version +number in it.</p> + <p> +By convention, source NMU changelog entries start with the line +<example> + * Non-maintainer upload +</example></p></sect1> + - <sect1>Transferring the files to master + <sect1 id="nmu-patch">Source NMUs and the Bug Tracking System <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.) +Maintainers other than the official package maintainer should make as +few changes to the package as possible, and they should always send a +patch as a unified context diff (<tt>diff -u</tt>) detailing their +changes to the Bug Tracking System. <p> - 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. +What if you are simply recompiling the package? In this case, the +process is different for porters than it is for non-porters, as +mentioned above. If you are not a porter and are doing an NMU that +simply requires a recompile (i.e., a new shared library is available +to be linked against, a bug was fixed in +<package>debhelper</package>), there must still be a changelog entry; +therefore, there will be a patch. If you are a porter, you are +probably just doing a binary 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</em> but not actually <em>closed</em> 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</email>, 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</em> retain the +entry in the changelog file documenting the non-maintainer upload. + - <sect1>Uploads via Chiark + <sect1 id="nmu-build">Building source NMUs <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>. +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> - The program <tt/dupload/ support uploads to chiark, please - refer to the documentation that comes with the program, - for details. +Make sure you do <em>not</em> 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</prgn> is as +<tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>. Of course, +set <var>porter-email</var> to your email address. This will do a +binary-only build of only the architecture-dependant portions of the +package, using the `binary-arch' target in <file>debian/rules</file>. + + + <sect1 id="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</em> waiting period for the `frozen' distribution. + <p> +However, if you are a porter doing an NMU for `unstable', the above +guidelines for porting should be followed, with two variations. +Firstly, the acceptable waiting period -- 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> +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>Uploads via Erlangen + <sect1 id="quinn-diff"> + <heading><package>quinn-diff</package> <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</>. +<package>quinn-diff</package> is used to locate the differences from +one architecture to another. For instance, it could tell you which +packages need to be ported for architecture <var>Y</var>, based on +architecture <var>X</var>. + + + <sect1 id="buildd"> + <heading><package>buildd</package> <p> - The 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. +The <package>buildd</package> system is used as a distributed, +client-server build distribution system. It is usually used in +conjunction with <em>auto-builders</em>, which are ``slave'' hosts +which simply check out and attempt to auto-build packages which need +to be ported. There is also an email interface to the system, which +allows porters to ``check out'' a source package (usually one which +cannot yet be autobuilt) and work on it. <p> - 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. +<package>buildd</package> is not yet available as a package; however, +most porting efforts are either using it currently or planning to use +it in the near future. It collects a number of as yet unpackaged +components which are currently very useful and in use continually, +such as <prgn>sbuild</prgn> and <prgn>wanna-build</prgn>. <p> - The program <tt/dupload/ support uploads to erlangen, - please refer to the documentation that comes with the - program, for details. +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. - <sect1>Uploading to the non-us server + + + + <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</tt> asking that the old +location be removed. Give details on what you did, since it might be +a <prgn>dinstall</prgn> 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</tt> asking that the +package be removed. Make sure you indicate which distribution the +package should be removed from. + <p> +If in doubt concerning whether a package is disposable, email +<email>debian-devel@lists.debian.org</email> asking for opinions. +Also of interest is the <prgn>apt-cache</prgn> program from the +<package>apt</package> package. When invoked as <tt>apt-cache showpkg +/var/cache/apt/pkgcache.bin <var>package</var></tt>, the program will +show details for <var>package</var>, including reverse depends. + + <sect1>Removing packages from <tt>Incoming</tt> <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, +If you decide to remove a package from <tt>Incoming</tt>, it is nice +but not required to send a notification of that to the appropriate +announce list (either <email>debian-changes@lists.debian.org</email> +or <email>debian-devel-changes@lists.debian.org</email>). - <item> read the diff and decide on each part of it - themselves, or + <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</tt> asking to remove the package with the +obsolete name. - <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> + + + <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</email> 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</email> 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</email>. + <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</email>. + <p> +If you take over an old package, you probably want to be listed as the +package's official maintainer in the bug system. This will happen +automatically once you upload a new version with an updated +<tt>Maintainer:</tt> 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</email> 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</tt>. 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> 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> - In addition, the normal maintainer should <em/always/ - include an entry in the changelog file documenting the - non-maintainer upload. +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</tt> file to +<email>XXX-done@bugs.debian.org</email>, where <var>XXX</var> is your +bug number. + - <sect>Maintainer changes + <sect id="lintian-reports">Lintian reports + <p> +You should periodically get the new <package>lintian</package> from +`unstable' and check over all your packages. Alternatively you can +check for your maintainer email address at the <url +id="http://www.debian.org/lintian/" name="online lintian report">. +That report, which is updated automatically, contains +<prgn>lintian</prgn> reports against the latest version of the +distribution (usually from 'unstable') using the latest +<package>lintian</package>. + + + <sect>Reporting lots of bugs at once <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/. +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</package> so that an error or warning +is emitted. + <p> +If you report more than 10 bugs on the same topic at once, it is +recommended that you send a message to +<email>debian-devel@lists.debian.org</email> describing your intention +before submitting the report. This will allow other developers to +verify that the bug is a real problem. In addition, it will help +prevent a situation in which several maintainers start filing the same +bug report simultaneously. + <p> +Note that when sending lots of bugs on the same subject, you should +send the bug report to <email>maintonly@bugs.debian.org</email> so +that the bug report is not forwarded to the bug distribution mailing +list. + + + <chapt id="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</package> + <p> +<package>dpkg-dev</package> contains the tools (including +<prgn>dpkg-source</prgn>) required to unpack, build and upload Debian +source packages. These utilities contain the fundamental, low-level +functionality required to create and manipulated packages; as such, +they are required for any Debian maintainer. + + + <sect id="lintian"> + <heading><package>lintian</package> + <p> +<package>Lintian</package> dissects Debian packages and reports bugs +and policy violations. It contains automated checks for many aspects +of Debian policy as well as some checks for common errors. The use of +<package>lintian</package> has already been discussed in <ref +id="upload-checking"> and <ref id="lintian-reports">. + + + <sect id="debhelper"> + <heading><package>debhelper</package> + <p> +<package>debhelper</package> is a collection of programs that can be +used in <file>debian/rules</file> to automate common tasks related to +building binary Debian packages. Programs are included to install +various files into your package, compress files, fix file permissions, +integrate your package with the Debian menu system. + <p> +Unlike <package>debmake</package>, <package>debhelper</package> is +broken into several small, granular commands which act in a consistent +manner. As such, it allows a greater granularity of control than +<package>debmake</package>. + + + <sect id="debmake"> + <heading><package>debmake</package> + <p> +<package>debmake</package>, a pre-cursor to +<package>debhelper</package>, is a less granular +<file>debian/rules</file> assistant. It includes two main programs: +<prgn>deb-make</prgn>, which can be used to help a maintainer convert +a regular (non-Debian) source archive into a Debian source package; +and <prgn>debstd</prgn>, which incorporates in one big shot the same +sort of automated functions that one finds in +<package>debhelper</package>. + <p> +The consensus is that <package>debmake</package> is now deprecated in +favor of <package>debhelper</package>. However, it's not a bug to use +<package>debmake</package>. + + <sect id="yada"> + <heading><package>yada</package> <p> - 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. +<package>yada</package> is a new packaging helper tool with a slightly +different philosophy. It uses a <file>debian/packages</file> file to +auto-generate other necessary files in the <file>debian/</file> +subdirectory. + + + <sect id="cvs-buildpackage"> + <heading><package>cvs-buildpackage</package> + <p> +<package>cvs-buildpackage</package> provides the capability to inject +or import Debian source packages into a CVS repository, build a Debian +package from the CVS repository, and helps in integrating upstream +changes into the repository. + <p> +These utilities provide an infrastructure to facilitate the use of CVS +by Debian maintainers. This allows one to keep separate CVS branches +of a package for <em>stable</em>, <em>unstable</em>, and possibly +<em>experimental</em> distributions, along with the other benefits of +a version control system. + + + <sect id="dupload"> + <heading><package>dupload</package> <p> +<package>dupload</package> is a package and a script to automagically +upload Debian packages to the Debian archive, to log the upload, and +to send mail about the upload of a package. You can configure it for +new upload locations or methods. - <chapt>Handling bug reports<p> - <sect>Reporting lots of bugs at once + <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>debuild</prgn>, which is a wrapper around +<prgn>dpkg-buildpackage</prgn>. + + + <sect id="debget"> + <heading><package>debget</package> <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> +<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: +-->