Clarify instructions for replacing/renaming binary packages,

pointing out that using Provides is sometimes advisable. Closes:
#467102

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

diff --git a/debian/changelog b/debian/changelog
index 8f4ffa21065f689b41bfa661fb43c89eca6e9127..437adcab3c2815ab180f75c9b36cff54e4389dc6 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -37,6 +37,9 @@ developers-reference (3.4.0) UNRELEASED; urgency=low
     need to inform the maintainers you reassign the bug to. Also
     hint to using cloned bugs to avoid re-reporting. Heavily based
     on patch by Marc Haber - thanks for the work! Closes: #484806
+  * Clarify instructions for replacing/renaming binary packages,
+    pointing out that using Provides is sometimes advisable. Closes:
+    #467102
 
  -- Marc 'HE' Brockschmidt <he@debian.org>  Sun, 01 Jun 2008 16:26:33 +0200
 

diff --git a/pkgs.dbk b/pkgs.dbk
index 05ebf11c3233ea14a1397939c17b4138226f4216..1e0b29d9593b81ade4d436d9ef8540f87a748780 100644 (file)
--- a/pkgs.dbk
+++ b/pkgs.dbk
@@ -1339,14 +1339,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