Update section on what to do when distfiles change.

3 files changed, 49 insertions, 28 deletions

diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 2ab4c6d77a0..2c533f168fb 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.16 2005/05/26 16:32:42 wiz Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.17 2005/05/29 09:10:42 wiz Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Notes on fixes for packages</title>
@@ -475,16 +475,23 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2</programlisting>
       <para> Sometimes authors of a software package make some
         modifications after the software was released, and they put up a
         new distfile without changing the package's version number. If a
-        package is already in pkgsrc at that time, the md5 checksum will
-        no longer match. The correct way to work around this is to
-        update the package's md5 checksum to match the package on the
-        master site (beware, any mirrors may not be up to date yet!),
-        and to remove the old distfile from
-        ftp.NetBSD.org's
-        <filename>/pub/NetBSD/packages/distfiles</filename> directory.
-        Furthermore, a mail to the package's author seems appropriate
-        making sure the distfile was really updated on purpose, and that
-        no trojan horse or so crept in.  </para>
+        package is already in pkgsrc at that time, the checksum will
+        no longer match. The contents of the new distfile should be
+	compared against the old one before changing anything, to make
+	sure the distfile was really updated on purpose, and that
+        no trojan horse or so crept in.
+	Then, the correct way to work around this is to
+	set <varname>DIST_SUBDIR</varname> to a unique directory name,
+	usually based on <varname>PKGNAME_NOREV</varname>. In case this
+	happens more often, <varname>PKGNAME</varname> can be used (thus
+	including the <filename>nbX</filename> suffix) or a date stamp
+	can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>.
+	Do not forget regenerating the <filename>distinfo</filename> file
+	after that, since it contains the <varname>DIST_SUBDIR</varname>
+	path in the filenames.
+        Furthermore, a mail to the package's authors seems appropriate
+	telling them that changing distfiles after releases without
+	changing the file names is not good practice. </para>
     </sect2>
   </sect1>
 
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html
index b85beaeb3a5..358ce1c20dd 100644
--- a/doc/pkgsrc.html
+++ b/doc/pkgsrc.html
@@ -9892,17 +9892,27 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2
             modifications after the software was released, and they
             put up a new distfile without changing the package's
             version number. If a package is already in pkgsrc at
-            that time, the md5 checksum will no longer match. The
-            correct way to work around this is to update the
-            package's md5 checksum to match the package on the
-            master site (beware, any mirrors may not be up to date
-            yet!), and to remove the old distfile from
-            ftp.NetBSD.org's <code class=
-            "filename">/pub/NetBSD/packages/distfiles</code>
-            directory. Furthermore, a mail to the package's author
-            seems appropriate making sure the distfile was really
-            updated on purpose, and that no trojan horse or so
-            crept in.</p>
+            that time, the checksum will no longer match. The
+            contents of the new distfile should be compared against
+            the old one before changing anything, to make sure the
+            distfile was really updated on purpose, and that no
+            trojan horse or so crept in. Then, the correct way to
+            work around this is to set <code class=
+            "varname">DIST_SUBDIR</code> to a unique directory
+            name, usually based on <code class=
+            "varname">PKGNAME_NOREV</code>. In case this happens
+            more often, <code class="varname">PKGNAME</code> can be
+            used (thus including the <code class=
+            "filename">nbX</code> suffix) or a date stamp can be
+            appended, like <code class=
+            "varname">${PKGNAME_NOREV}-YYYYMMDD</code>. Do not
+            forget regenerating the <code class=
+            "filename">distinfo</code> file after that, since it
+            contains the <code class="varname">DIST_SUBDIR</code>
+            path in the filenames. Furthermore, a mail to the
+            package's authors seems appropriate telling them that
+            changing distfiles after releases without changing the
+            file names is not good practice.</p>
           </div>
         </div>
 
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 0ca4b438423..fe1283b756c 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -3983,13 +3983,17 @@ ap-aolserver, www/openacs. Try to be consistent with them.
 Sometimes authors of a software package make some modifications after the
 software was released, and they put up a new distfile without changing the
 package's version number. If a package is already in pkgsrc at that time, the
-md5 checksum will no longer match. The correct way to work around this is to
-update the package's md5 checksum to match the package on the master site
-(beware, any mirrors may not be up to date yet!), and to remove the old
-distfile from ftp.NetBSD.org's /pub/NetBSD/packages/distfiles directory.
-Furthermore, a mail to the package's author seems appropriate making sure the
+checksum will no longer match. The contents of the new distfile should be
+compared against the old one before changing anything, to make sure the
 distfile was really updated on purpose, and that no trojan horse or so crept
-in.
+in. Then, the correct way to work around this is to set DIST_SUBDIR to a unique
+directory name, usually based on PKGNAME_NOREV. In case this happens more
+often, PKGNAME can be used (thus including the nbX suffix) or a date stamp can
+be appended, like ${PKGNAME_NOREV}-YYYYMMDD. Do not forget regenerating the
+distinfo file after that, since it contains the DIST_SUBDIR path in the
+filenames. Furthermore, a mail to the package's authors seems appropriate
+telling them that changing distfiles after releases without changing the file
+names is not good practice.
 
 13.3. Configuration gotchas