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