From 773091507a161b580f7065006938a2f167ea23cc Mon Sep 17 00:00:00 2001 From: aph Date: Wed, 15 Jul 1998 02:46:13 +0000 Subject: [PATCH] plaster my name all over it format the SGML like I like it git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@629 313b444b-1b9f-4f58-a734-7bb04f332e8d --- developers-reference.sgml | 1110 +++++++++++++++++-------------------- 1 file changed, 518 insertions(+), 592 deletions(-) diff --git a/developers-reference.sgml b/developers-reference.sgml index f457a5c..4921045 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -1,213 +1,184 @@ + within the document --> %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 &version;, &date; - -<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>version &version;, &date; + <copyright> +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">. 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>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 <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/. +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. +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. +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. +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. +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: - +Before you decide to work in the Debian Project you have to read the +<url id="http://www.debian.org/social_contract" name="Debian Social +Contract">. + <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. + <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: +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. + <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. +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. + <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). +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> - 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. +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 emails) should +also post to that list and an experienced developer will volunteer to +help. + - <sect id="mailing-lists">Mailing lists<p> + <chapt>Internet Servers - 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. + <sect id="mailing-lists">Mailing lists <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. +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> - 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/. +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> - 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. +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. + + <sect>The master server <p> @@ -217,306 +188,274 @@ Suite 330, Boston, MA 02111-1307, USA. <sect>The WWW servers <p> - <chapt>The Debian Archive<p> - + + <chapt>The Debian Archive + <sect>Overview <p> +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/. - The Debian GNU/Linux distribution consists of a lot of - Debian packages (<tt/.deb/'s, currently more than 1000) and - a few additional files (documentation, installation disk - images, etc.). - <p> - Here is an example directory tree of a complete Debian - distribution: - <example> - main/ - main/binary-all/ - main/binary-all/admin/ - main/binary-all/base/ - main/binary-all/comm/ - main/binary-all/devel/ - ... - main/binary-i386/ - main/binary-m86k/ - ... - main/source/ - main/disks-i386/ - main/disks-m68k/ - ... - - contrib/ - contrib/binary-all/ - contrib/binary-i386/ - contrib/binary-m86k/ - ... - contrib/source/ - - non-free/ - non-free/binary-all/ - non-free/binary-i386/ - non-free/binary-m86k/ - ... - non-free/source/ - </example> - <p> - As you can see, the top-level directory of the distribution - contains three directories, namely <em>main</>, - <em>contrib</>, and <em>non-free</>. These directories are - called <em>sections</>. - <p> - In each section, there is a directory with the source - packages (source), a directory for each supported - architecture (binary-i386, binary-m86k, etc.), and a - directory for architecture independent packages - (binary-all). - <p> - The <em/main/ section contains additional directories which - holds the disk images and some essential pieces of - documentation required for installing the Debian - distribution on a specific architecture (disks-i386, - disks-m68k, etc.). - <p> - The <em/binary/ and <em/source/ directories are divided - further into <em/sub-sections/. - <p> - - <sect>Sections - <p> - The <em>main section</> is what makes up the <em>Debian - GNU/Linux distribution</>. This is because the packages in - the other two sections do not fully comply with all our - guidelines. + <sect>Sections <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 <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> - 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. +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> - Packages in the <em>contrib</> section have to apply to - the DFSG, but fail other requirements. +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> - (The Debian Policy Manual contains a more exact definition - of the three sections. This is just meant to be an - introduction.) +Packages in the <em>contrib</> section have to apply to the DFSG, but +fail other requirements. <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. +(The Debian Policy Manual contains a more exact definition of the +three sections. This is just meant to be an introduction.) <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 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.) - <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. + <sect>Architectures <p> - The Linux 2.0 kernel supports Intel, DEC Alphas, SUN Sparcs, - M68000 machines (like Atari and Amiga), MIPS, and - PowerPC. +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> - 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. +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. Debian +2.0 supports Intel and m68k architectures. + <sect>Sub sections <p> +The sections <em/main/, <em/contrib/, and <em/non-free/ are split into +<em/sub sections/, to simplify the installation process and the +maintainance of the archive. - 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 one <tt/.tar.gz/ file or a - <tt/.orig.tar.gz/ and a <tt/.diff.gz/ file. +There are two types of Debian packages, namely <em/source/ and +<em/binary/ packages. <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. +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 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. +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> - The <tt/.dsc/ lists all components of the source package - together with checksums (md5sums) and some additional info - about the package (maintainer, version, etc.). +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.). + <sect>Distribution directories <p> +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. - 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.'') + <sect>Release code names <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. +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/, Debian 2.1 will be called <em/slink/, etc. <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. +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> - Note, that development is continued during the ``freeze'' - period, since a new ``unstable'' distribution will be - created at that time. +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> - 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. +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. - <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> + + <chapt>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. +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: +This has the following advantages: <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. + + <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. + + <item> +It is helpful to the people who live off unstable (and form our first +line of testers); we should encourage these people. + + <item> +I think the announcements gives us a better feel of what is going on, +and what is new, in the project. + + <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. + + <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) </list> <sect>Uploading a package - <p> <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 for its +handling. This is usually generated by <prgn/dpkg-genchanges/. <p> - - This file is a control file with the following fields: +This file is a control file with the following fields: <list compact> <item><tt/Format/ <item><tt/Date/ @@ -532,232 +471,219 @@ Suite 330, Boston, MA 02111-1307, USA. <item><tt/Files/ </list> <p> - - 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. +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. <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. +The first time a version is uploaded which corresponds to a particular +upstream version the original source tar file should be uploaded and +included in the <tt/.changes/ file; subsequent times the very same tar +file should be used to build the new diffs and <tt/.dsc/ files, and it +need not then be uploaded. <p> - - By default <prgn/dpkg-genchanges/ and - <prgn/dpkg-buildpackage/ will include the original source - tar-file if and only if the Debian revision part of the - source version number is <tt/0/ or <tt/1/, indicating a - new upstream version. This behaviour may be modified by - using <tt/-sa/ to always include it or <tt/-sd/ to always - leave it out. +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. - 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. - <p> <sect1>Transferring the files to master <p> - To upload a package, you need a personal account on the - master server. Just log in via ftp and transfer the - files to - `<tt>/home/Debian/ftp/private/project/Incoming</tt>.' - (You cannot upload to Incoming on master using anonymous - FTP--you must use your user-name and password.) - <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 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.) <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. + <sect1>Uploads via Chiark <p> - If you have a slow network connection to the master - system, there are two alternatives: You can upload files - to Incoming via a cron-driven upload queue in Europe on - ftp.chiark.greenend.org.uk. For details connect to chiark - using anonymous FTP and read - <tt>/pub/debian/private/project/README.how-to-upload</tt>. - <p> - The program <tt/dupload/ support uploads to chiark, please - refer to the documentation that comes with the program, - for details. +If you have a slow network connection to the master system, there are +two alternatives: You can upload files to Incoming via a cron-driven +upload queue in Europe on ftp.chiark.greenend.org.uk. For details +connect to chiark using anonymous FTP and read +<tt>/pub/debian/private/project/README.how-to-upload</tt>. <p> +The program <tt/dupload/ support uploads to chiark, please refer to +the documentation that comes with the program, for details. + <sect1>Uploads via Erlangen <p> - Another cron-driven upload queue is available in Germany: - Just upload the files via anonymous FTP to - <tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>. +Another cron-driven upload queue is available in Germany: Just upload +the files via anonymous FTP to +<tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>. <p> - The upload must be a complete Debian upload, as you would - put it into master's incoming, i.e. a <tt/.changes/ files - along with the other files mentioned in the - <tt/.changes/. The queue daemon also checks that the - <tt/.changes/ is correctly PGP-signed by a Debian - developer, so that no bogus files can find their way to - master via the queue. Please also make sure that the - <tt/Maintainer:/ field in the <tt/.changes/ contains - *your* e-mail address. The address found there is used for - all replies, just as on master. +The upload must be a complete Debian upload, as you would put it into +master's incoming, i.e. a <tt/.changes/ files along with the other +files mentioned in the <tt/.changes/. The queue daemon also checks +that the <tt/.changes/ is correctly PGP-signed by a Debian developer, +so that no bogus files can find their way to master via the +queue. Please also make sure that the <tt/Maintainer:/ field in the +<tt/.changes/ contains *your* e-mail address. The address found there +is used for all replies, just as on master. <p> - There's no need to move your files into a second directory - after the upload as on chiark. And, in any case, you - should get some mail reply from the queue daemon what - happened to your upload. Hopefully it should have been - moved to master, but in case of errors you're notified, - too. +There's no need to move your files into a second directory after the +upload as on chiark. And, in any case, you should get some mail reply +from the queue daemon what happened to your upload. Hopefully it +should have been moved to master, but in case of errors you're +notified, too. <p> - The program <tt/dupload/ support uploads to erlangen, - please refer to the documentation that comes with the - program, for details. +The program <prgn/dupload/ support uploads to erlangen, please refer +to the documentation that comes with the program, for details. <p> <sect1>Uploading to the non-us server <p> - To upload a package to the <em/non-us/ server you just - have to transfer the files via anonymous ftp to - <tt>ftp://nonus.debian.org/pub/debian-non-US/Incoming</tt>. - Note, that the <tt>.changes</tt> file must have a valid - PGP signature from one of the keys of the developers - keyring. - <p> +To upload a package to the <em/non-us/ server you just have to +transfer the files via anonymous ftp to <url +id="ftp://nonus.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 keyring. + <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/. +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 <tt/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 <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. +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. + <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 +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, - - <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. + <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/. - <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. +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/. <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. + - <chapt>Handling bug reports<p> + <chapt>Handling bug reports <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. +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 <email/maintonly@bugs.debian.org/ so that the +bug report is not forwarded to the bug distribution mailing list. + -</book> + </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: +--> -- 2.30.2