Changes between Version 23 and Version 24 of PortfileRecipes

Timestamp:

Apr 12, 2011, 9:59:40 PM (13 years ago)

Author:

ryandesign (Ryan Carsten Schmidt)

Comment:

add section on replaced_by

PortfileRecipes

@@ -279 +279 @@
 Another reason to want compiler variants is if the software installs a library, or uses a library built with a different gcc.
 Subtle and difficult-to-find errors can occur if a library and the program using it are not both compiled with the same compiler.
+
+
+
+== Replacing and renaming ports == #replaced-by
+
+When a software project is renamed, a new port is created with the project's new name. The new port should usually not be created from scratch; instead it should be copied from the old port, using the `svn copy` command, to preserve the port's Subversion history. For example, when the developers of the OSXvnc project renamed it to Vine Server, the new vineserver port was created by copying the old osxvnc port:
+
+{{{
+cd $(port dir osxvnc)/../
+svn copy osxvnc vineserver
+}}}
+
+Then the new port (vineserver, in this example) is edited, including changing the `name` field to the project's new name, most likely changing the `version`, possibly changing the `homepage`, `master_sites` and `livecheck`, and anything else related to the name change. It's also a good idea to include the project's old name in the new port's `description` and `long_description` so that users searching for it by its old name can find it.
+
+The old port (osxvnc) needs to be kept around for some time, and converted into a stub port marked as having been replaced by the new port, so that users who already had the old port installed will learn about the new port and will be prompted (via `port outdated`) to upgrade to it. There are several steps to this process:
+
+ 1. Add the `replaced_by` line, indicating the name of the port by which this port has been replaced, for example `replaced_by vineserver`. This causes MacPorts, when running `sudo port upgrade osxvnc`, to deactivate osxvnc and to install vineserver in its place. In order for osxvnc to appear in `port outdated` in the first place, however, its `version`, `revision` or `epoch` must be increased, so:
+ 1. Increase the port's `version`, `revision` or `epoch`. Customarily, the old port's version is set to the version of the replacement port. So, when osxvnc @3.0_1 was replaced by vineserver @3.1_0, osxvnc's `version` was set to 3.1 and its `revision` dropped to 0 to match the new vineserver port. If the software was only renamed, without changing its version number, then increase the old port's `revision`.
+ 1. The above handles upgrades for users who already had the port installed, but does not prevent users from actually installing the old port. To prevent that, there should be a pre-configure block informing the user of the replacement and terminating the installation attempt; see the complete Portfile example below. Note that this should be a pre-configure block, not a pre-fetch block, because some users like to fetch all outdated ports' distfiles using `sudo port fetch outdated` (for example because they temporarily have access to a faster network connection) and we don't want to interrupt that.
+ 1. Remove all directives related to fetching files: `master_sites`, `patch_sites`, `fetch.*`, `cvs.*`, `svn.*`, `hg.*`, `git.*`, or `bzr.*` directives. Set just a single directive `distfiles` to indicate there are no distfiles to fetch.
+ 1. Remove any existing directives and blocks for any of the phases: fetch, extract, patch, configure, build, destroot, install, archive, activate and deactivate (other than the pre-configure block added above).
+ 1. Remove any `depends_*`, `PortGroup` and `notes` directives and any `variant` and `platform` blocks.
+ 1. Remove the `files` directory if present since those files are no longer needed.
+ 1. Since the old port will no longer be updated, set `livecheck.type none`.
+ 1. Optionally, update the description and long_description to indicate the port has been replaced.
+
+Here is a complete example stub port:
+
+{{{
+# -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4
+# $Id$
+
+PortSystem          1.0
+
+name                osxvnc
+replaced_by         vineserver
+version             3.1
+categories          aqua vnc
+platforms           darwin
+maintainers         ryandesign
+license             GPL-2+
+
+description         a full-featured VNC server (formerly OSXvnc)
+
+long_description    Vine Server (formerly OSXvnc) is a full-featured VNC \
+                    server for Mac OS X providing remote access to the GUI, \
+                    keyboard and mouse using any VNC client.
+
+homepage            http://www.testplant.com/products/vine_server
+
+distfiles
+
+pre-configure {
+    ui_error "${name} has been renamed to ${replaced_by}. Please install ${replaced_by} instead."
+    return -code error "obsolete port"
+}
+
+livecheck.type      none
+}}}
+
+The reason for leaving a stub port (rather than deleting the old port immediately) is to provide a seamless upgrade process for people who installed the port under its old name. So the stub port should not be deleted until after most users can be expected to have used `sudo port selfupdate` and `sudo port upgrade outdated`. Since some users do not update frequently, it is recommended that the old port remain for no less than one year after the `replaced_by` line is added.
+
+Sometimes a port is replaced not because the software project was renamed, but because its functionality was rolled into another existing project. (For example, the functionality of the glut port was rolled into the mesa port.) The same process applies, except that the wording of the `ui_error` should be changed from "renamed to" to "replaced by".
+
+{{{
+pre-configure {
+    ui_error "${name} has been replaced by ${replaced_by}; please install ${replaced_by} instead."
+    return -code error "obsolete port"
+}
+}}}
+
+This also applies in case a [ticket:14540 -devel port] was created but will no longer be updated and is being replaced by a corresponding non-devel port. (For example, the xz-devel port was replaced by the xz port.)