selfupdate: Add --migrate: rebuilds w/o downgrade

For 'port migrate' we want to automatically re-install MacPorts base
even if there is no never version available. We do have 'port -f
selfupdate' that would achieve this, but 'port -f selfupdate' would also
downgrade any pre-release installations to the latest released version.

Since a pre-release version could have changed the database layout,
a downgrade from pre-release versions is not safe. Instead provide
--migrate (mostly for internal use by 'port migrate') so that users with
a pre-release version can be prompted to upgrade their base installation
manually.

doc/port-selfupdate.1.txt

@@ -9,7 +9,7 @@ port-selfupdate - Upgrade MacPorts itself and update the port definition files.
 SYNOPSIS
 --------
 [cmdsynopsis]
-*port* [*-qvdf*] *selfupdate* [--nosync]
+*port* [*-qvdf*] *selfupdate* [--nosync] [--migrate]
 
 DESCRIPTION
 -----------
@@ -29,6 +29,11 @@ OPTIONS
     Only check for updates - and install if available - for MacPorts itself. Do
     not update the ports tree.
 
+*--migrate*::
+    Rebuild even if no new version is available, upgrade if a new version is
+    available. Contrary to *-f*, this flag will prevent downgrades. This flag is
+    useful when upgrading to a newer macOS major version.
+
 include::global-flags.txt[]
 
 *-q*::
@@ -39,9 +44,9 @@ include::global-flags.txt[]
     currently installed one, but always rebuild and reinstall MacPorts.
     +
     You can use this to downgrade from a beta or development version to the
-    latest release. Note that there is no guarantee that there have not been
-    made incompatible and irreversible changes to MacPorts' internal data
-    structures, making a downgrade impossible.
+    latest release. Note that there is no guarantee that no incompatible and
+    irreversible changes have been made to MacPorts' internal data structures,
+    which can make downgrading impossible.
 
 EXAMPLES
 --------

src/macports1.0/selfupdate.tcl

@@ -158,7 +158,10 @@ proc selfupdate::main {{optionslist {}} {updatestatusvar {}}} {
         }
     }
 
-    if {$use_the_force_luke || $comp > 0} {
+    # Check whether we need to re-install base because of a migration
+    set migrating [expr {[info exists options(ports_selfupdate_migrate)] && $options(ports_selfupdate_migrate)}]
+
+    if {$use_the_force_luke || $comp > 0 || ($comp == 0 && $migrating)} {
         if {[info exists options(ports_dryrun)] && $options(ports_dryrun)} {
             ui_msg "$macports::ui_prefix MacPorts base is outdated, selfupdate would install $macports_version_new (dry run)"
         } else {

src/port/port.tcl

@@ -4468,7 +4468,7 @@ array set cmd_opts_array {
                  depends description epoch exact glob homepage line
                  long_description maintainer maintainers name platform
                  platforms portdir regex revision variant variants version}
-    selfupdate  {nosync}
+    selfupdate  {migrate nosync}
     space       {{units 1} total}
     activate    {no-exec}
     deactivate  {no-exec}