X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=pkgs.dbk;h=8f1f36b9cd1928e497af1ffbc5e1afcd372d2d29;hb=e81cdebedab690ef881d87af6f533e51c026565c;hp=f6206d0a939b8f5d3452d5e82ab1463648e1e2f8;hpb=fd33305f4875ecb7266063a04b549aad9532ecce;p=developers-reference.git

diff --git a/pkgs.dbk b/pkgs.dbk
index f6206d0..8f1f36b 100644
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -28,14 +28,18 @@ description of the package, the license of the prospective package, and the
 current URL where it can be downloaded from.
 </para>
 <para>
-You should set the subject of the bug to ``ITP: <replaceable>foo</replaceable>
--- <replaceable>short description</replaceable>'', substituting the name of the
-new package for <replaceable>foo</replaceable>.  The severity of the bug report
-must be set to <literal>wishlist</literal>.  If you feel it's necessary, send
-a copy to &email-debian-devel; by putting the address in the
-<literal>X-Debbugs-CC:</literal> header of the message (no, don't use
-<literal>CC:</literal>, because that way the message's subject won't indicate
-the bug number).
+You should set the subject of the bug to <literal>ITP: 
+<replaceable>foo</replaceable> -- <replaceable>short
+description</replaceable></literal>, substituting the name of the new
+package for <replaceable>foo</replaceable>. 
+The severity of the bug report must be set to <literal>wishlist</literal>.
+Please send a copy to &email-debian-devel; by using the X-Debbugs-CC
+header (don't use CC:, because that way the message's subject won't
+indicate the bug number). If you are packaging so many new packages (>10)
+that notifying the mailing list in seperate messages is too disruptive,
+do send a summary after filing the bugs to the debian-devel list instead.
+This will inform the other developers about upcoming packages and will
+allow a review of your description and package name.
 </para>
 <para>
 Please include a <literal>Closes:
@@ -662,11 +666,25 @@ procedure</ulink>.
 If the bug is real but it's caused by another package, just reassign the bug to
 the right package.  If you don't know which package it should be reassigned to,
 you should ask for help on <link linkend="irc-channels">IRC</link> or
-on &email-debian-devel;.  Please make sure that the
-maintainer(s) of the package the bug is reassigned to know why you reassigned
-it.
+on &email-debian-devel;.  Please inform the maintainer(s) of the package
+you reassign the bug to, for example by Cc:ing the message that does the
+reassign to <email>packagename@packages.debian.org</email> and explaining
+your reasons in that mail. Please note that a simple reassignment is
+<emphasis>not</emphasis> e-mailed to the maintainers of the package
+being reassigned to, so they won't know about it until they look at
+a bug overview for their packages.
 </para>
 <para>
+If the bug affects the operation of your package, please consider
+cloning the bug and reassigning the clone to the package that really
+causes the behavior. Otherwise, the bug will not be shown in your
+package's bug list, possibly causing users to report the same bug over
+and over again. You should block "your" bug with the reassigned, cloned
+bug to document the relationship.
+</para>
+</listitem>
+<listitem>
+<para>
 Sometimes you also have to adjust the severity of the bug so that it matches
 our definition of the severity.  That's because people tend to inflate the
 severity of bugs to make sure their bugs are fixed quickly.  Some bugs may even
@@ -721,9 +739,9 @@ several developers working on the same package.
 </listitem>
 <listitem>
 <para>
-Once a corrected package is available in the <literal>unstable</literal>
-distribution, you can close the bug.  This can be done automatically, read
-<xref linkend="upload-bugfix"/> .
+Once a corrected package is available in the archive, the bug should be
+closed indicating the version in which it was fixed. This can be done
+automatically, read <xref linkend="upload-bugfix"/>.
 </para>
 </listitem>
 </orderedlist>
@@ -1325,14 +1343,20 @@ occur too often anyway.
 <section id="s5.9.3">
 <title>Replacing or renaming packages</title>
 <para>
-When you make a mistake naming your package, you should follow a two-step
-process to rename it.  First, set your <filename>debian/control</filename> file
-to replace and conflict with the obsolete name of the package (see the <ulink
-url="&url-debian-policy;">Debian Policy Manual</ulink> for
-details).  Once you've uploaded the package and the package has moved into the
-archive, file a bug against <literal>ftp.debian.org</literal> asking to remove
-the package with the obsolete name.  Do not forget to properly reassign the
-package's bugs at the same time.
+When the upstream maintainers for one of your packages chose to
+rename their software (or you made a mistake naming your package),
+you should follow a two-step process to rename it. In the first
+step, change the <filename>debian/control</filename> file to
+reflect the new name and to replace, provide and conflict with the
+obsolete package name (see the <ulink url="&url-debian-policy;">
+Debian Policy Manual</ulink> for details).  Please note that you
+should only add a <literal>Provides</literal> relation if all
+packages depending on the obsolete package name continue to work
+after the renaming. Once you've uploaded the package and the package
+has moved into the archive, file a bug against <literal>
+ftp.debian.org</literal> asking to remove the package with the
+obsolete name (see <xref linkend="removing-pkgs"/>).  Do not forget
+to properly reassign the package's bugs at the same time.
 </para>
 <para>
 At other times, you may make a mistake in constructing your package and wish to
@@ -2261,7 +2285,7 @@ available in <literal>unstable</literal>, but not affecting the version in
 <listitem>
 <para>
 It must be available on all architectures on which it has previously been built
-in <literal>unstable</literal>.  <xref linkend="madison"/> may be of interest
+in <literal>unstable</literal>.  <xref linkend="dak-ls"/> may be of interest
 to check that information;
 </para>
 </listitem>