Changes between Version 27 and Version 28 of PortfileRecipes

Timestamp:

Jun 4, 2011, 3:58:22 PM (13 years ago)

Author:

ryandesign (Ryan Carsten Schmidt)

Comment:

rewrite stealth updates section

PortfileRecipes

@@ -147 +147 @@
 
 == Stealth updates == #stealth-updates
-Some software may update their distfile with new changes without changing the version number (e.g., it stays example-1.2.tar.gz). The safest way to deal with this is to keep the port's version unchanged (e.g., stays at 1.2) while increasing the revision.  This however will cause a checksum mismatch for those who already have the previous distfile.  The correct solution to this problem is to change dist_subdir. By default, dist_subdir is ${name}; change it so that it includes a subdirectory named for the version and revision:
-{{{
-dist_subdir   ${name}/${version}_${revision}
-}}}
-This example is from the [browser:trunk/dports/lang/sicp/Portfile sicp Portfile].
+Although they would be wise not to do this, some software developers occasionally update their distfile with new changes without changing the distfile's name (e.g., it stays example-1.2.tar.gz).
+The port's `checksums` then need to be updated, but the `version` stays the same (e.g. stays at 1.2).
+So that users will see the update, the `revision` is increased, but users who already have the previous distfile would then experience a checksum mismatch.
+To avoid this, you must also set `dist_subdir`.
+By default, `dist_subdir` is ${name}; change it so that it includes a subdirectory named for the version number and the distfile revision number (start at 1 and increment by 1 each time this version's distfile is stealth-updated):
+{{{
+dist_subdir   ${name}/${version}_1
+}}}
+This line should be removed when the next proper version of the software is released.
+It's a good idea to add a comment above the dist_subdir line reminding yourself (or the next committer) to do this.
+
+Using the ${revision} variable in the `dist_subdir` definition isn't usually a good idea, because the `revision` is supposed to allow the portfile author to offer the user an upgrade that is unrelated to the upstream software version.
+
+Compare the old distfile with the new one.
+(In most cases, the old distfile can be downloaded from the MacPorts distfiles mirror.)
+Sometimes the new distfile does not differ materially from the old one (e.g. the gz or bz2 files are different but the underlying tar files are identical, or there are only changes in files that the port does not install).
+If you can determine that this has happened, then you don't want to force users to rebuild since it would be of no benefit to them.
+In this case, do not increase the port's `revision`, but do update the `checksums` and add the `dist_subdir` line as above.
+
+For software whose developers habitually stealth-update their software, further measures may need to be taken, such as those employed by the dcraw and molden ports.
+But ideally, convince the developers to refrain from stealth-updating.
 
 See also the next entry on [#unversioned-distfiles unversioned distfiles].