Update section on what to do when distfiles change.

1 files changed, 21 insertions, 11 deletions

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>