[pkgsrc/trunk]: pkgsrc/doc Update section on what to do when distfiles change.

[wiz <wiz%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/42a7a5e53133
branches:  trunk
changeset: 494740:42a7a5e53133
user:      wiz <wiz%pkgsrc.org@localhost>
date:      Sun May 29 09:10:40 2005 +0000

description:
Update section on what to do when distfiles change.

diffstat:

 doc/guide/files/fixes.xml |  29 ++++++++++++++++++-----------
 doc/pkgsrc.html           |  32 +++++++++++++++++++++-----------
 doc/pkgsrc.txt            |  16 ++++++++++------
 3 files changed, 49 insertions(+), 28 deletions(-)

diffs (112 lines):

diff -r 4b4b82e5c042 -r 42a7a5e53133 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Sun May 29 08:41:34 2005 +0000
+++ b/doc/guide/files/fixes.xml Sun May 29 09:10:40 2005 +0000
@@ -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 @@
       <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 -r 4b4b82e5c042 -r 42a7a5e53133 doc/pkgsrc.html
--- a/doc/pkgsrc.html   Sun May 29 08:41:34 2005 +0000
+++ b/doc/pkgsrc.html   Sun May 29 09:10:40 2005 +0000
@@ -9892,17 +9892,27 @@
             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 -r 4b4b82e5c042 -r 42a7a5e53133 doc/pkgsrc.txt
--- a/doc/pkgsrc.txt    Sun May 29 08:41:34 2005 +0000
+++ b/doc/pkgsrc.txt    Sun May 29 09:10:40 2005 +0000
@@ -3983,13 +3983,17 @@
 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