From 28de5c7acd18559872dcaf574c484d758cd50f46 Mon Sep 17 00:00:00 2001 From: aph Date: Mon, 21 Sep 1998 08:16:33 +0000 Subject: [PATCH] complete stuff for this round of textual overhauls, notably adding section on removing, renaming, orphaning packages git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@654 313b444b-1b9f-4f58-a734-7bb04f332e8d --- debian/changelog | 33 +++++- developers-reference.sgml | 206 ++++++++++++++++++++++++++------------ 2 files changed, 174 insertions(+), 65 deletions(-) diff --git a/debian/changelog b/debian/changelog index 920e458..787be65 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,8 +1,35 @@ developers-reference (2.4.1.4) unstable; urgency=low - * debian/rules: added source-depends rule (experimental) - - -- Adam P. Harris Tue, 28 Jul 1998 01:03:47 -0400 + * fill in Section "The master server" a bit; other servers to follow + * in Section "Distribution directories", mention that distributions + are always in 'dists' subdir of the Debian archive; talk about + 'proposed-updates' + * in Section "Release code names", talk about 'sid' a bit + * in Section "Interim releases", talk about how non-maintainers should + use the BTS, and bug severity "fixed" (closes Bug#17524) + * in Section "Generating the changes file", talk about how to set the + distribution in the debian/changelog file (i.e., "frozen unstable") + * add a new Section "Checking the package prior to upload" to Section + "Uploading a package", mentioning lintian and other tests one should + do prior to uploading + * add new Section "Notification that a new package has been installed" + in Section "Uploading a package", talking about dinstall and the + override file a bit + * add new Sections "Moving packages", "Removing packages", "Replacing or + renaming packages", and "Orphaning a package" (closes Bug#26650) + * add new Section "Bugs in your packages", talking about maintainer + duties with respect to bugs + * add new Section "Lintian reports" under "Handling bugs reports", + talking about how maintainers should check their packages with lintian + every now and then, alternatively pointing them to the lintian web + pages + * clarify, a bit, the use of "section" and "subsection", bringing it + into line with the usage in the Policy Manual and Packaging Manual + * grammar and markup changes throughout + * debian/rules: added a crude source-depends rule, which renders more + explicit what is used to build this package + + -- Adam P. Harris Mon, 21 Sep 1998 00:51:46 -0400 developers-reference (2.4.1.3) unstable; urgency=low diff --git a/developers-reference.sgml b/developers-reference.sgml index 9ee6d90..fc42aff 100644 --- a/developers-reference.sgml +++ b/developers-reference.sgml @@ -6,9 +6,11 @@ @@ -245,21 +247,6 @@ non-free/source/ As you can see, the top-level directory of the distribution contains three directories, namely main, contrib, and non-free. These directories are called sections. -

In each section, there is a directory with the source packages (source), a directory for each supported architecture (binary-i386, @@ -272,14 +259,15 @@ installing the Debian distribution on a specific architecture (disks-i386, disks-m68k, etc.).

The Sections

-The main section is what makes up the Debian GNU/Linux +The main section is what makes up the Debian GNU/Linux distribution. This is because the packages in the other two -sections do not fully comply with all our guidelines. +sections do not fully comply with all our guidelines. As such, they +are not officially part of Debian.

For example, every package in the main distribution must fully comply with the Debian Free Software Guidelines (DFSG) and with all @@ -294,7 +282,8 @@ infrastructure (such as our bug-tracking system and mailing lists) for non-free software packages.

Packages in the contrib section have to apply to the DFSG, but -fail other requirements. +fail other requirements. For instance, they might depend on non-free +packages.

(The Debian Policy Manual contains a more exact definition of the three sections. This is just meant to be an introduction.) @@ -302,9 +291,9 @@ three sections. This is just meant to be an introduction.) 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 - On the other hand, a CD-ROM vendor could easily check the individual package licenses of the packages in Debian GNU/Linux 1.3 is only available for Intel platforms. Debian 2.0 supports Intel and m68k architectures. The next version of Debian -is likely to also support Sparc, PPC, and Alpha, if not more. +is likely to also support Alpha, PPC, and Sparc architectures, if not +more. - Sub sections + Subsections

The sections Packages @@ -381,29 +376,30 @@ 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.''

-After about two months of development, the -After another month or a little longer, the -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 now and then. However, these -updates are tested very carefully and have to be acknowledged -individually to reduce the risk of introducing new bugs. You can find -proposed additions to `stable' in the +This development cycle is based on the assumption that the `unstable' +distribution becomes `stable' after passing a period of testing as +`frozen'. Unfortunately, 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 acknowledged individually to +reduce the risk of introducing new bugs. You can find proposed +additions to `stable' in the Note, that development is continued during the ``freeze'' period, -since a new ``unstable'' distribution will be created at that time. +since a new `unstable' distribution is be created when the older +`unstable' is moved to `frozen'.

In summary, there is always a Release code names

@@ -449,13 +445,13 @@ If you want to create a new package for the Debian distribution, you should first check the page. Checking -the WNPP ensures that effort is not duplicated or wasted; namely, that -no-one is already working on packaging that software. Assuming no-one -else is currently working on your prospective package, you have to -send a short email to There are a number of reasons why we ask maintainers to follow these steps. @@ -525,6 +521,21 @@ This file is a control file with the following fields: All of them are mandatory for a Debian upload. See the list of control fields in the +Notably, the debian/changelog file, should indicate which distribution the +package is intended for. There are three possible values for this +field: `stable', `unstable', or `frozen'; 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 `stable' and +`unstable' distributions, then you might put `stable unstable' in the +debian/changelog's distribution field. Or, if Debian has +been frozen, and you want to get a bug-fix release into `frozen', you +would set the distribution to `frozen unstable'. Note that setting +the distribution to `stable' means that the pacakge will be placed +into the proposed-updates directory of the Debian archive for +further testing, before it is actually included in `stable'. +

The first time a version is uploaded which corresponds to a particular upstream version the original source tar file should be uploaded and @@ -772,15 +783,87 @@ for a while, send an email to Moving, removing, renaming, and orphaning packages +

+Some archive manipulation operation are not automated in the Debian +upload process. This chapter gives guidelines in what to do in these +cases. + + Moving packages +

+Sometimes a package will change either it's section or it's +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 +In this case, it is sufficient to edit the package control information +normally and re-upload the package (see the Removing packages +

+If for some reason you want to completely remove a package (say, if it +is an old compatability library which is not longer required), you +need to file a bug against +If in doubt concerning whether a package is disposable, email +Replacing or renaming packages +

+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 debian/control file to replace and conflict with the +obsolete name of the package (see the Orphaning a package +

+If you can no longer maintain a package, then you should set the +package maintainer to Debian QA +<debian-qa@lists.debian.org> and email +Handling bug reports - Bugs in your packages + Monitoring bugs

If you want to be a good maintainer, you should periodically check the for your packages. The BTS contains all the open bugs against your packages.

+Maintainers interact with the BTS via email addresses at +, or, if you have +installed the /usr/doc/debian/bug-*. +

+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). + + When bugs are closed by new uploads +

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 @@ -788,20 +871,19 @@ 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.

-Maintainers interact with the BTS via email addresses at -/usr/doc/debian/bug-* from the Lintian reports

You should periodically get the new . That page, which is -updated automatically, contains lintian reports against the latest -version of the package (usually from 'unstable') using the latest -. +That page, which is updated automatically, contains Reporting lots of bugs at once -- 2.30.2