From: aph Date: Tue, 14 Jul 1998 19:27:06 +0000 (+0000) Subject: \Initial Import\\ X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=95ea0c14fdc37e203e990ae8b8eee26d95c466f6 \Initial Import\\ git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@625 313b444b-1b9f-4f58-a734-7bb04f332e8d --- 95ea0c14fdc37e203e990ae8b8eee26d95c466f6 diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 0000000..26b61ed --- /dev/null +++ b/debian/changelog @@ -0,0 +1,123 @@ +developers-reference (2.4.1.1) frozen unstable; urgency=low + + * Orphaned package + + -- Christian Schwarz Thu, 14 May 1998 21:56:36 +0200 + +developers-reference (2.4.1.0) frozen unstable; urgency=low + + * New version numbering scheme: + + - The version numbers are independent of dpkg now, but all policy + manuals (the Debian Policy Manual, the Debian Packaging Manual, and + the Debian Developer's Reference) share the same version numbering + scheme. + + - The first three digits of the version number specify the + `Standards-Version.' This number is incremented with each policy + change. The fourth digit represents the `patch-level,' which may + differ between the manuals. + + If only the patch-level digit is incremented, no changes in policy + have been made, except bug fixes and clarifications. Packages only + have to specify the first three digits of the version number in the + `Standards-Version' field of their source packages. + + * Uploaded to frozen and unstable. This is a documentation-only + package and the changes to the manual are relevant for hamm. + + * No changes to the Developer's Reference + + -- Christian Schwarz Mon, 13 Apr 1998 17:54:43 +0200 + +developers-reference (0.5) unstable; urgency=low + + * Changes to the Developer's Reference: + + - Changed section 1.2 Registering as a Debian developer: + + signatures from formal certification service are _NOT_ accepted + anymore + + images of ID documents have to be PGP or RSA signed + (as requested by James Troup) + + - Use current date instead of in manual + + * Updated FSF's address (reported by Lintian) + + -- Christian Schwarz Sat, 7 Mar 1998 13:52:15 +0100 + +developers-reference (0.4) unstable; urgency=low + + * Changes to the Developer's Reference: + + - Renamed chapter 4 into `Package uploads' + + - New section 4.2.5 Uploading to the non-us server + + - Changed section 4.4 Interim releases: + + non-maintainer releases should not close bugs + + normal maintainer must at least read the patch provided with + the non-maintainer release + + - New chapter 5 Handling bug reports: + + when reporting more then 10 bugs on the same topic, a message + has to be sent to debian-devel and the `maintonly' address + should be used + + - Lots of typos fixed + + * Compressed SGML source code + + * Added support for doc-base to register the Developer's Reference + to the online documentation systems dwww and dhelp + + * Upgraded to standards version 2.4.0.0 (no changes) + + -- Christian Schwarz Fri, 30 Jan 1998 21:58:34 +0100 + +developers-reference (0.3) unstable; urgency=low + + * Put lost sections from Policy Manual 2.1.3.3 back in: + - Generating the changes file (for uploads) + - Announcing package uploads + * New section about Debian Mentors + * debian/rules: Don't use debstd anymore + * debian/rules: Compress changelog file (fixes:#15441) + * Fixed link to WNPP list (fixes:#16201) + * Added menu entry (fixes:#15708) + + -- Christian Schwarz Wed, 24 Dec 1997 13:54:33 +0100 + +developers-reference (0.2) unstable; urgency=low + + * New chapter about `The Debian Archive' describing the structure + of our FTP server and the development process + * Added note that new maintainers have to read the Social Contract + and have to know where to find the Policy and Packaging Manuals + * PGP key ring is not distributed via dpkg but in doc/ of the FTP + server + * Added note that cross posting between Debian lists is depreciated + * New list of advantages why new packages should be discussed on + debian-devel before they are uploaded + * Added section about how packages are uploaded + * Added note that the Security Managers may do interim releases without + contacting the maintainer + * Removed chapter about bug tracking system (will be included in + a new manual released soon) + * Some minor changes + * Include SGML source in package + * Don't use `2-up' style for PostScript version + * Upgraded to Standards 2.3.0.1 + + -- Christian Schwarz Sun, 2 Nov 1997 20:53:26 +0100 + +developers-reference (0.1) unstable; urgency=low + + * Initial Release. + + -- Christian Schwarz Tue, 8 Jul 1997 00:19:49 +0200 + +Local variables: +mode: debian-changelog +add-log-mailing-address: "schwarz@debian.org" +End: diff --git a/debian/control b/debian/control new file mode 100644 index 0000000..504ccca --- /dev/null +++ b/debian/control @@ -0,0 +1,19 @@ +Source: developers-reference +Section: doc +Priority: extra +Maintainer: Debian QA +Standards-Version: 2.4.1.0 + +Package: developers-reference +Architecture: all +Suggests: doc-base +Description: Debian Developer's Reference + This package contains the Debian Developer's Reference. + . + Table of Contents: + . + 1 Applying to Become a Maintainer + 2 Internet Servers + 3 The Debian Archive + 4 Package uploads + 5 Handling bug reports diff --git a/debian/copyright b/debian/copyright new file mode 100644 index 0000000..1a22a15 --- /dev/null +++ b/debian/copyright @@ -0,0 +1,24 @@ + +This is the Debian package of the Debian Developer's Reference. +It was assembled by Christian Schwarz . + +------------------------------------------------------------------------------ +Copyright of the Debian Developer's Reference: + +Copyright (c) 1997,1998 Christian Schwarz. + +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. + +This is distributed in the hope that it will be useful, but without +any warranty; without even the implied warranty of merchantability or +fitness for a particular purpose. See the GNU General Public License +for more details. + +A copy of the GNU General Public License is available as +/usr/doc/copyright/GPL in the Debian GNU/Linux distribution or on the +World Wide Web at 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. diff --git a/debian/dirs b/debian/dirs new file mode 100644 index 0000000..93d2e8a --- /dev/null +++ b/debian/dirs @@ -0,0 +1,4 @@ +usr/doc/developers-reference +usr/lib/menu +DEBIAN +usr/share/doc-base diff --git a/debian/menu b/debian/menu new file mode 100644 index 0000000..446437a --- /dev/null +++ b/debian/menu @@ -0,0 +1,4 @@ +?package(developers-reference):needs="dwww" section="Apps/Programming"\ + title="Debian Developer's Reference"\ + description="This manual explains how to become a Debian maintainer, how the Debian archive is organized, and the package developer's daily work."\ + command="/usr/doc/developers-reference/developers-reference.html/index.html" diff --git a/debian/postinst b/debian/postinst new file mode 100644 index 0000000..6a94bae --- /dev/null +++ b/debian/postinst @@ -0,0 +1,22 @@ +#!/bin/sh + +set -e + +case "$1" in + configure) + # continue below + ;; + + abort-upgrade|abort-remove|abort-deconfigure) + exit 0 + ;; + + *) + echo "postinst called with unknown argument \`$1'" >&2 + exit 0 + ;; +esac + +if [ -x /usr/sbin/install-docs ]; then + /usr/sbin/install-docs -i /usr/share/doc-base/developers-reference +fi diff --git a/debian/prerm b/debian/prerm new file mode 100644 index 0000000..b46d4c7 --- /dev/null +++ b/debian/prerm @@ -0,0 +1,5 @@ +#!/bin/sh + +if [ -x /usr/sbin/install-docs ]; then + /usr/sbin/install-docs -r developers-reference +fi diff --git a/debian/rules b/debian/rules new file mode 100755 index 0000000..8093639 --- /dev/null +++ b/debian/rules @@ -0,0 +1,64 @@ +#!/usr/bin/make -f + +package=developers-reference + +build: + $(checkdir) + debiandoc2html developers-reference.sgml + debiandoc2text developers-reference.sgml + gzip -9 developers-reference.text + touch build + +clean: + $(checkdir) + -rm -f build + -rm -rf developers-reference.html + -rm -rf developers-reference.text* + -rm -f `find . -name "*~"` + -rm -rf debian/tmp debian/files* core debian/substvars + +binary-indep: checkroot build + $(checkdir) + -rm -rf debian/tmp + install -d debian/tmp + cd debian/tmp && install -d `cat ../dirs` + cp -a developers-reference.html debian/tmp/usr/doc/developers-reference/ + cp developers-reference.text.gz debian/tmp/usr/doc/developers-reference/ + cp developers-reference.sgml debian/tmp/usr/doc/developers-reference/ + gzip -9 debian/tmp/usr/doc/developers-reference/developers-reference.sgml + cp debian/{copyright,changelog} debian/tmp/usr/doc/developers-reference/ + gzip -9 debian/tmp/usr/doc/developers-reference/changelog + cp debian/menu debian/tmp/usr/lib/menu/developers-reference + cp developers-reference.desc debian/tmp/usr/share/doc-base/developers-reference + cp debian/{control,postinst,prerm} debian/tmp/DEBIAN/ + chmod +x debian/tmp/DEBIAN/{postinst,prerm} + dpkg-gencontrol + chown -R root.root debian/tmp + chmod -R go=rX debian/tmp + dpkg --build debian/tmp .. + debiandoc2ps -pa4 -1 -O developers-reference.sgml | gzip -9v > ../developers-reference.ps.gz + dpkg-distaddfile -fdebian/files developers-reference.ps.gz byhand - + GZIP=-9v tar zcf ../developers-reference.html.tar.gz developers-reference.html + dpkg-distaddfile -fdebian/files developers-reference.html.tar.gz byhand - + cp developers-reference.text.gz .. + dpkg-distaddfile -fdebian/files developers-reference.text.gz byhand - + +binary-arch: checkroot build + $(checkdir) +# There are no architecture-dependent files to be uploaded +# generated by this package. If there were any they would be +# made here. + +define checkdir + test -f debian/rules +endef + +# Below here is fairly generic really + +binary: binary-indep binary-arch + +checkroot: + $(checkdir) + test root = "`whoami`" + +.PHONY: binary binary-arch binary-indep clean checkroot diff --git a/developers-reference.desc b/developers-reference.desc new file mode 100644 index 0000000..2c20640 --- /dev/null +++ b/developers-reference.desc @@ -0,0 +1,14 @@ +Document: developers-reference +Title: Debian Developer's Reference +Author: Christian Schwarz +Section: Apps/Programming + +Format: debiandoc-sgml +Files: /usr/doc/developers-reference/developers-reference.sgml.gz + +Format: text +Files: /usr/doc/developers-reference/developers-reference.text.gz + +Format: HTML +Index: /usr/doc/developers-reference/developers-reference.html/index.html +Files: /usr/doc/developers-reference/developers-reference.html/*.html diff --git a/developers-reference.sgml b/developers-reference.sgml new file mode 100644 index 0000000..53ee410 --- /dev/null +++ b/developers-reference.sgml @@ -0,0 +1,758 @@ + + + + + + + + +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 + +<copyright>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> + +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> + +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> + + <toc sect> + + <chapt>Applying to Become a Maintainer<p> + + <sect>Getting started + <p> + + So, you've read all the documentation, you understand what + everything in the <prgn/hello/ example package is for, and + you're about to Debianise your favourite package. How do + you actually become a Debian developer so that your work can + be incorporated into the Project? + <p> + + Firstly, subscribe to <prgn/debian-devel/ if you haven't + already. Send the word <tt/subscribe/ in the <em/Subject/ + of a mail to <email/debian-devel-REQUEST@lists.debian.org/. + In case of problems contact the list administrator at + <email/listmaster@lists.debian.org/. + <p> + + You should subscribe and lurk for a bit before doing any + coding, and you should post about your intentions to work on + something to avoid duplicated effort. + <p> + + If you do not have a PGP key yet generate one. You should + probably read the PGP manual, as it has much important + information which is critical to its security. Many more + security failures are due to human error than to software + failure or high-powered spy techniques. + <p> + + Due to export restrictions by the United States government + some Debian packages, including PGP, have been moved to an + ftp site outside of the United States. You can find the + current locations of those packages on + <ftpsite/ftp.debian.org/ in the + <ftppath>/pub/debian/README.non-US</> file. + <p> + + If you live in a country where use of cryptography even for + authentication is forbidden then please contact us so we can + make special arrangements. This does not apply in France, + where I believe only encryption and not authentication is + forbidden. + <p> + + <sect>Registering as a Debian developer + <p> + + Before you decide to work in the Debian Project you have to + read the ``Debian Social Contract'' (available on + <tt/www.debian.org/). + <p> + After that, you should send a message to + <email/new-maintainer@debian.org/ to register as an + 'offical' Debian developer so that you will be able to + upload your packages. + <p> + The message should say what you've done and who you are, and + should ask for an account on master and to be subscribed to + debian-private (the developers-only mailing list). It should + contain your PGP or RSA public key (extracted using `pgp + -kxa', in the case of PGP) for the database of keys which is + distributed on the FTP server + (<tt>doc/debian-keyring.tar.gz</tt>). Please be sure to + sign your request message with your chosen PGP or RSA + key. In addition, you have to mention that you've read the + ``Debian Social Contract'' (see above) and you are expected + to know where to find the ``Debian Policy Manual'' and the + ``Debian Packaging Manual.'' + <p> + Please be sure to include your preferred login name on + master (seven characters or less), as well as the E-mail + address at which you'd prefer to be subscribed to + debian-private (typically this will be either your primary + mail address or your new debian.org address). + <p> + You should also include some mechanism by which we can + verify your real-life identity. For example, any of the + following mechanisms would suffice: + + <list compact> + <item>A PGP or RSA key signed by any well-known signature, + such as any current Debian developer. + <item>A scanned (or physically mailed) copy of any formal + documents certifying your identity (such as a birth + certificate, national ID card, U.S. Driver's License, + etc.). Please sign the image with your PGP or RSA key. + </list> + + The following mechanisms are discouraged, but are acceptable if + neither of the first two mechanisms is practical: + <list compact> + <item>A pointer to a phone listing at which you could be + reached (at our expense). This phone listing should + be verifiable independently through external means + such as a national directory-listing service or other + authoritative source. + <item>Any other mechanism by which you can establish your + real-life identity with reasonable certainty. + </list> + + We're sorry about the inconvenience of requiring proof of + identity, but for the moment, such measures are + unfortunately the only way we can ensure the security and + reliability of our distribution. + <p> + + Once this information is received and processed, you should + be contacted with information about your new Debian + maintainer account. If you don't hear anything within 7-10 + days, please re-send your original message--the + new-maintainer volunteers are typically overworked, and + mistakes do occasionally happen. + <p> + + <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> + + 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 + <p> + + <sect>The FTP servers + <p> + + <sect>The WWW servers + <p> + + <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 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. + <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, DEC Alphas, SUN Sparcs, + M68000 machines (like Atari and Amiga), MIPS, and + PowerPC. + <p> + Debian GNU/Linux 1.3 is only available for Intel + platforms. One of the goals for Debian 2.0 is to support + some of the other architectures, too. + <p> + + <sect>Sub sections + <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 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> + + If you have a look at the Debian FTP server or one of its + mirrors, you'll discover that there is one additional + directory level on top of the directory tree, as described + in the previous chapter. These directories are the + <em/distribution directories/. + <p> + There is always a distribution called <em/stable/ and one + called <em/unstable/. This reflects the development process + of the Debian project: + <p> + The ``development'' is done in the <em/unstable/ + distribution (that's why this distribution is sometimes + called <em/development distribution/). Every Debian + developer can update his/her packages in this distribution + at any time. Thus, the contents of this distribution changes + from day to day and since no special effort is done to test + this distribution it's sometimes ``unstable.'' + <p> + After about two months of development, the <em/unstable/ + distribution is copied in a new distribution directory, + called <em/frozen/. After that, no changes are allowed to + the frozen distribution, except bug fixes. (That's why it's + called ``frozen.'') + <p> + After another month or a little longer, the <em/frozen/ + distribution is renamed to <em/stable/, overriding the old + <em/stable/ distribution, which is removed at that time. + <p> + This development cycle is based on the assumption, that the + once `unstable' distribution finally becomes `stable' after + passing one month of testing. Unfortunately, a few bugs + still remain--that's why the stable distribution is updated + every few weeks. However, these updates are tested very + carefully and have to be acknowledged individually to reduce + the risk of introducing new bugs. + <p> + Note, that development is continued during the ``freeze'' + period, since a new ``unstable'' distribution will be + created at that time. + <p> + In summary, there is always a <em/stable/ and an + <em/unstable/ distribution available and the <em/frozen/ + distribution shows up for a month from time to time. + <p> + + <sect>Release code names + <p> + Every released Debian distribution has a <em/code name/: + Debian 1.1 is called <em/buzz/, Debian 1.2 <em/rex/, Debian + 1.3 <em/bo/, Debian 2.0 <em/hamm/, etc. + <p> + Since the Debian has an open development (i.e. everyone can + participate and follow the development) even the + ``development versions'' (unstable) are distributed via the + Internet on the Debian FTP server. This FTP server is + mirrored by lots of other systems. Thus, if we'd call the + directory which contains the development version simply + `unstable', then we would have to rename it to `stable' when + the version is released, which would cause all FTP mirrors + to re-get the whole distribution (which is already very + large!). + <p> + On the other hand, if we would call the distribution + directories <em>Debian-x.y</em> from the beginning, people + would think that Debian release <em>x.y</> is + available. (This happened in the past, where a CD-ROM vendor + built a Debian 1.0 CD-ROM based on a pre-1.0 development + version. That's the reason why the first official Debian + release was 1.1, and not 1.0.) + <p> + Thus, the names of the distribution directories in the + archive should stay the same during the development period + and after the release but there may be symbolic links, which + can be changed. + <p> + That's why the distribution directories use the <em/code + names/ and there are symbolic links <em/stable/, + <em/unstable/, <em/frozen/, etc. which point to the + appriopriate release directories. + <p> + + <chapt>Package uploads<p> + + <sect>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: + + <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) + </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/. + <p> + + This file is a control file with the following fields: + <list compact> + <item><tt/Format/ + <item><tt/Date/ + <item><tt/Source/ + <item><tt/Binary/ + <item><tt/Architecture/ + <item><tt/Version/ + <item><tt/Distribution/ + <item><tt/Urgency/ + <item><tt/Maintainer/ + <item><tt/Description/ + <item><tt/Changes/ + <item><tt/Files/ + </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. + <p> + + The first time a version is uploaded which corresponds to + a particular upstream version the original source tar file + should be uploaded and included in the <tt/.changes/ file; + subsequent times the very same tar file should be used to + build the new diffs and <tt/.dsc/ files, and it need not + then be uploaded. + <p> + + By default <prgn/dpkg-genchanges/ and + <prgn/dpkg-buildpackage/ will include the original source + tar-file if and only if the Debian revision part of the + source version number is <tt/0/ or <tt/1/, indicating a + new upstream version. This behaviour may be modified by + using <tt/-sa/ to always include it or <tt/-sd/ to always + leave it out. + <p> + + If no original source is included in the upload then the + original source tar-file used by <prgn/dpkg-source/ when + constructing the <tt/.dsc/ file and diff to be uploaded + <em/must/ be byte-for-byte identical with the one already + in the archive. If there is some reason why this is not + the case then the new version of the original source + should be uploaded, possibly by using the <tt/-sa/ flag. + <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. + <p> + + <sect1>Uploads via Chiark + <p> + If you have a slow network connection to the master + system, there are two alternatives: You can upload files + to Incoming via a cron-driven upload queue in Europe on + ftp.chiark.greenend.org.uk. For details connect to chiark + using anonymous FTP and read + <tt>/pub/debian/private/project/README.how-to-upload</tt>. + <p> + The program <tt/dupload/ support uploads to chiark, please + refer to the documentation that comes with the program, + for details. + <p> + + <sect1>Uploads via Erlangen + <p> + Another cron-driven upload queue is available in Germany: + Just upload the files via anonymous FTP to + <tt>ftp://ftp.uni-erlangen.de/pub/Linux/debian/UploadQueue</>. + <p> + The upload must be a complete Debian upload, as you would + put it into master's incoming, i.e. a <tt/.changes/ files + along with the other files mentioned in the + <tt/.changes/. The queue daemon also checks that the + <tt/.changes/ is correctly PGP-signed by a Debian + developer, so that no bogus files can find their way to + master via the queue. Please also make sure that the + <tt/Maintainer:/ field in the <tt/.changes/ contains + *your* e-mail address. The address found there is used for + all replies, just as on master. + <p> + There's no need to move your files into a second directory + after the upload as on chiark. And, in any case, you + should get some mail reply from the queue daemon what + happened to your upload. Hopefully it should have been + moved to master, but in case of errors you're notified, + too. + <p> + The program <tt/dupload/ support uploads to erlangen, + please refer to the documentation that comes with the + program, for details. + <p> + + <sect1>Uploading to the non-us server + <p> + To upload a package to the <em/non-us/ server you just + have to transfer the files via anonymous ftp to + <tt>ftp://nonus.debian.org/pub/debian-non-US/Incoming</tt>. + Note, that the <tt>.changes</tt> file must have a valid + PGP signature from one of the keys of the developers + keyring. + <p> + + <sect>Announcing package uploads + <p> + When a package is uploaded an announcement should be posted + to one of the debian-changes lists. The announcement should + give the (source) package name and version number, and a + very short summary of the changes, in the <prgn/Subject/ + field, and should contain the PGP-signed <tt/.changes/ file. + Some additional explanatory text may be added before the + start of the <tt/.changes/ file. + <p> + If a package is released with the <tt/Distribution:/ set to + <tt/stable/, the announcement is sent to + <email/debian-changes@lists.debian.org/. + <p> + If a package is released with <tt/Distribution:/ set to + <tt/unstable/, <tt/experimental/, or <tt/frozen/ (when + present), the announcement should be posted to + <email/debian-devel-changes@lists.debian.org/ instead. + <p> + + <sect>Interim releases + <p> + Under certain circumstances it is necessary for someone + other than the usual package maintainer to make a release of + a package. For example, a porter for another architecture + may have to make some small changes to the source package + and does not wish to wait with uploading their release until + the main maintainer has incorporated the patch, or a serious + security problem may have come to light requiring immediate + attention. + <p> + When a security bug is detected a fixed package should be + uploaded as soon as possible. In this case, the Debian + Security Managers should get in contact with the package + maintainer to make sure a fixed package is uploaded within a + reasonable time (less than 48 hours). If the package + maintainer cannot provide a fixed package fast enough or if + he/she cannot be reached in time, the Security Manager + may upload a fixed package. + <p> + When someone other than the usual maintainer releases a + package they should add a new component to the + <var/debian-revision/ component of the version number--that + is, the portion after the (last) hyphen. This extra + component will start at <tt/1/. This is to avoid `stealing' + one of the usual maintainer's version numbers, possibly + disrupting their work. If there is no <var/debian-revision/ + component in the version number then one should be created, + starting at <tt/1/. + <p> + If it is absolutely necessary for someone other than the + usual maintainer to make a release based on a new upstream + version then the person making the release should start with + the <var/debian-revision/ value <tt/0.1/. The usual + maintainer of a package should start their + <var/debian-revision/ numbering at <tt/1/. + <p> + Maintainers other than the usual package maintainer should + make as few changes to the package as possible, and they + should always send a unified context diff (<tt/diff -u/) + detailing their changes to the bug tracking system properly + flagged with the correct package so that the usual + maintainer is kept aware of the situation. If the + non-maintainer upload fixes some bugs, the bug reports + should not be closed. However, the person making the + non-maintainer release should send a short message to the + bug tracking system to all the fixed bugs explaining that + they have been fixed. This way, the maintainer and other + people will get notified about that. + <p> + The normal maintainer should do at least one of + <list compact> + <item> apply the diff, + + <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> + + <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. + <p> + + <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>