- Explain to reassign/close bugs of removed packages. closes: #130255

- Updates the note about software subject to US patents. closes: #142798
- New Section "Contacting other maintainers" under "Beyond packaging"
  Document the package@packages.debian.org alias; closes: #114553
- New Section "Package's information" under Resources
  Document http://packages.debian.org/<package>,
  http://bugs.debian.org/<package> and the madison utility.
- Sec "Reporting bugs": added http://bugs.debian.org/from:email@isp.com
- Sec "Handling bugs": added http://bugs.debian.org/login@debian.org

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1673 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/common.ent b/common.ent
index 9bdc400dac1799223fdcd3ccc99ea67e6895519e..a34159682c8cd5960c79465b9864102a770163ec 100644 (file)
--- a/common.ent
+++ b/common.ent
@@ -30,6 +30,11 @@
 <!entity lists-host "lists.debian.org">
 <!entity archive-host "archive.debian.org">
 <!entity keyserver-host "keyring.debian.org">
 <!entity lists-host "lists.debian.org">
 <!entity archive-host "archive.debian.org">
 <!entity keyserver-host "keyring.debian.org">

+<!entity packages-host "packages.debian.org">
+<!entity bugs-host "bugs.debian.org">
+<!entity pts-host "packages.qa.debian.org">
+<!entity ftp-master-host "ftp-master.debian.org">
+<!entity non-us-host "non-us.debian.org">

 
 <!entity url-debian-policy "http://&www-debian-org;/doc/debian-policy/">
 <!-- deprecate, this is dead
 
 <!entity url-debian-policy "http://&www-debian-org;/doc/debian-policy/">
 <!-- deprecate, this is dead

diff --git a/debian/changelog b/debian/changelog
index eaeb9311a635a928f36a991f2bd7467ef2e4e940..719d98bcc2551b5d5bcabb4e4f6ca19d51c5ce59 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -54,6 +54,15 @@ developers-reference (3.0) unstable; urgency=low
       closes: #123586
     - removed some cruft in `Announcing package uploads'
     - document the testing scripts; closes: #129445
       closes: #123586
     - removed some cruft in `Announcing package uploads'
     - document the testing scripts; closes: #129445

+    - Explain to reassign/close bugs of removed packages. closes: #130255
+    - Updates the note about software subject to US patents. closes: #142798
+    - New Section "Contacting other maintainers" under "Beyond packaging"
+      Document the package@packages.debian.org alias; closes: #114553
+    - New Section "Package's information" under Resources
+      Document http://packages.debian.org/<package>,
+      http://bugs.debian.org/<package> and the madison utility.
+    - Sec "Reporting bugs": added http://bugs.debian.org/from:email@isp.com
+    - Sec "Handling bugs": added http://bugs.debian.org/login@debian.org

 
   * Antoine Hulin:
     - update French translation
 
   * Antoine Hulin:
     - update French translation

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 6609c1b5a6dae6a18d164c395d515f93a6510390..9c8c8c3e85cf217befe4c91464504b90b199a385 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->

-  <!entity cvs-rev "$Revision: 1.99 $">
+  <!entity cvs-rev "$Revision: 1.100 $">

   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--


@@ -763,7 +763,7 @@ sometimes literally unstable.
 The testing distribution is generated automatically by taking
 packages from unstable if they satisfy certain criteria. Those
 criteria should ensure a good quality for packages within testing.
 The testing distribution is generated automatically by taking
 packages from unstable if they satisfy certain criteria. Those
 criteria should ensure a good quality for packages within testing.

-The <ref id="testing-scripts"> are launched each day after the
+<ref id="testing-scripts"> are launched each day after the

 new packages have been installed.
        <p>
 After a period of development, once the release manager deems fit, the
 new packages have been installed.
        <p>
 After a period of development, once the release manager deems fit, the


@@ -889,13 +889,14 @@ non-buggy packages.
 The package must have been available in <em>unstable</em> for several days;
 the precise number depends on the urgency field's value of the upload. It
 is 10 days for low urgency, 5 days for medium urgency and 2 days for high
 The package must have been available in <em>unstable</em> for several days;
 the precise number depends on the urgency field's value of the upload. It
 is 10 days for low urgency, 5 days for medium urgency and 2 days for high

-urgency. Those delays may be doubled during a freeze.
+urgency. Those delays may be doubled during a freeze;

     <item>
 It must have less release-critical bugs than the version available
 in <em>testing</em>;
     <item>
 It must be available on all architectures on which it has been
     <item>
 It must have less release-critical bugs than the version available
 in <em>testing</em>;
     <item>
 It must be available on all architectures on which it has been

-previously built;
+previously built. <ref id="madison"> may be of interest to
+check that information;

     <item>
 It must not break any dependency of a package that is already available
 in <em>testing</em>;
     <item>
 It must not break any dependency of a package that is already available
 in <em>testing</em>;


@@ -923,6 +924,43 @@ inter-relationship is too complicated and can not be sorted out
 by the scripts. In that case, the release manager must be
 contacted, and he will force the inclusion of the packages.
 
 by the scripts. In that case, the release manager must be
 contacted, and he will force the inclusion of the packages.
 

+    <sect id="pkg-info">Package's information
+       <p>
+
+      <sect1 id="pkg-info-web">On the web
+       <p>
+Each package has several dedicated web pages that contains many
+informations. First <tt>http://&packages-host;/&lt;package&gt;</tt>
+will let you discover a presentation of each version of the package
+available in the various distributions. It includes its description,
+the dependencies and some links to download the package.
+       <p>
+The bug tracking system sorts the bugs by package, you can
+watch the bugs of each package at
+<tt>http://&bugs-host;/&lt;package&gt;</tt>.
+
+      <sect1 id="madison">The madison utility
+        <p>
+<prgn>madison</prgn> is a command-line utility that is available
+on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It
+uses a single argument corresponding to a package name. In result
+it displays which version of the package is available for each
+architecture and distribution combination. An example will let you
+understand easily.
+       <p>
+<example>
+$ madison libdbd-mysql-perl
+libdbd-mysql-perl |   1.2202-4 |        stable | source, alpha, arm, i386, m68k, powerpc, sparc
+libdbd-mysql-perl |   1.2216-2 |       testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
+libdbd-mysql-perl | 1.2216-2.0.1 |       testing | alpha
+libdbd-mysql-perl |   1.2219-1 |      unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
+</example>
+       <p>
+In this example, you can see that the version in unstable differs from
+the version in testing and that there has been a binary-only NMU of the
+package for the alpha architecture. Each time the package has been
+recompiled on most of the architectures.
+

 
    <chapt id="pkgs">Managing Packages
        <p>
 
    <chapt id="pkgs">Managing Packages
        <p>


@@ -1205,16 +1243,18 @@ the changes file last, you can simply copy your files to a temporary
 directory on <tt>ftp-master</tt> and then move them to
 <tt>&us-upload-dir;</tt>.
           <p>
 directory on <tt>ftp-master</tt> and then move them to
 <tt>&us-upload-dir;</tt>.
           <p>

-<em>Note:</em> Do not upload to <tt>ftp-master</tt> packages
-containing software that is patent-restricted by the United States
-government, nor any cryptographic packages which belong to
-<em>contrib</em> or <em>non-free</em>.  If you can't upload it to
-<tt>ftp-master</tt>, then neither can you upload it to the overseas
-upload queues on <tt>chiark</tt> or <tt>erlangen</tt>.  Uploads of
+<em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic
+packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of

 such software should go to <tt>non-us</tt> (see <ref
 such software should go to <tt>non-us</tt> (see <ref

-id="upload-non-us">).  If you are not sure whether U.S. patent
-controls or cryptographic controls apply to your package, post a
-message to &email-debian-devel; and ask.
+id="upload-non-us">). Furthermore packages containing code that is
+patent-restricted by the United States government can not be uploaded to
+<tt>ftp-master</tt>; depending on the case they may still be uploaded to
+<tt>non-US/non-free</tt> (it's in non-free because of distribution issues
+and not because of the license of the software). If you can't upload it to
+<tt>ftp-master</tt>, then neither can you upload it to the overseas upload
+queues on <tt>chiark</tt> or <tt>erlangen</tt>. If you are not sure
+whether U.S. patent controls or cryptographic controls apply to your
+package, post a message to &email-debian-devel; and ask.

          <p>
 You may also find the Debian packages <package>dupload</package> or
 <package>dput</package> useful
          <p>
 You may also find the Debian packages <package>dupload</package> or
 <package>dput</package> useful


@@ -1951,6 +1991,12 @@ If in doubt concerning whether a package is disposable, email
 package.  When invoked as <tt>apt-cache showpkg
 <var>package</var></tt>, the program will show details for
 <var>package</var>, including reverse depends.
 package.  When invoked as <tt>apt-cache showpkg
 <var>package</var></tt>, the program will show details for
 <var>package</var>, including reverse depends.

+       <p>
+Once the package has been removed, the package's bugs should be handled.
+They should either be reassigned to another package in the case where
+the actual code has evolved into another package (e.g. <tt>libfoo12</tt>
+was removed because <tt>libfoo13</tt> supersedes it) or closed if the
+software is simply no more part of Debian.

 
        <sect2>Removing packages from <tt>Incoming</tt>
          <p>
 
        <sect2>Removing packages from <tt>Incoming</tt>
          <p>


@@ -1972,7 +2018,8 @@ obsolete name of the package (see the <url id="&url-debian-policy;"
 name="Debian Policy Manual"> for details).  Once you've uploaded
 that package, and the package has moved into the archive, file a bug
 against <tt>ftp.debian.org</tt> asking to remove the package with the
 name="Debian Policy Manual"> for details).  Once you've uploaded
 that package, and the package has moved into the archive, file a bug
 against <tt>ftp.debian.org</tt> asking to remove the package with the

-obsolete name.
+obsolete name. Do not forget to properly reassign the package's bugs
+at the same time.

 
       <sect1 id="orphaning">Orphaning a package
        <p>
 
       <sect1 id="orphaning">Orphaning a package
        <p>


@@ -2036,6 +2083,8 @@ id="submit-bug">.
 If you want to be a good maintainer, you should periodically check the
 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
 packages.  The BTS contains all the open bugs against your packages.
 If you want to be a good maintainer, you should periodically check the
 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
 packages.  The BTS contains all the open bugs against your packages.

+You can check them by browsing this page:
+<tt>http://&bugs-host;/yourlogin@debian.org</tt>.

        <p>
 Maintainers interact with the BTS via email addresses at
 <tt>bugs.debian.org</tt>.  Documentation on available commands can be
        <p>
 Maintainers interact with the BTS via email addresses at
 <tt>bugs.debian.org</tt>.  Documentation on available commands can be


@@ -2195,6 +2244,12 @@ which are reported more than once, or setting bug severities to
 neither the bug submitter nor the package maintainer, you should
 not actually close the bug (unless you secure permission from the
 maintainer).
 neither the bug submitter nor the package maintainer, you should
 not actually close the bug (unless you secure permission from the
 maintainer).

+       <p>
+From time to time you may want to check what has been going on
+with the bug reports that you submitted. Take this opportunity to
+close those that you can't reproduce anymore. To find
+out all the bugs you submitted, you just have to visit
+<tt>http://&bugs-host;/your-email@your-isp.com</tt>.

 
       <sect1 id="submit-many-bugs">Reporting lots of bugs at once
        <p>
 
       <sect1 id="submit-many-bugs">Reporting lots of bugs at once
        <p>


@@ -2246,13 +2301,29 @@ he maintains and any Release Critical bugs filled against them.
 Send all this information to &email-debian-qa;, in order to let the 
 QA people do whatever is needed.
 
 Send all this information to &email-debian-qa;, in order to let the 
 QA people do whatever is needed.
 

-
+    <sect id="contacting-maintainers">Contacting other maintainers
+      <p>
+During your lifetime within Debian, you will have to contact other
+maintainers for various reasons. You may want to discuss a new
+way of cooperating between a set of related packages, or you may
+simply remind someone that a new upstream version is available
+and that you need it.
+      <p>
+Whatever the reason, it is a pain to lookup the email address of the
+maintainer of the package that you are interested in. Fortunately, you
+can use a simple email alias : <tt>&lt;package&gt;@&packages-host;</tt>.
+<tt>&lt;package&gt;</tt> can be the name of a source or a binary package.
+      <p>
+You may also be interested by contacting the persons who are
+subscribed to a given source package via the Package Tracking
+System. You can do so by using the <tt>&lt;package&gt;@&pts-host;</tt>
+address.

 
 
     <sect id="newmaint">
       <heading>Interacting with prospective Debian developers</heading>
       <p>
 
 
     <sect id="newmaint">
       <heading>Interacting with prospective Debian developers</heading>
       <p>

-Debian's success depends on it's ability to attract and retain new and
+Debian's success depends on its ability to attract and retain new and

 talented volunteers.  If you are an experienced developer, we
 recommend that you get involved with the process of bringing in new
 developers.  This section describes how to help new prospective
 talented volunteers.  If you are an experienced developer, we
 recommend that you get involved with the process of bringing in new
 developers.  This section describes how to help new prospective