volume: Deprecate '--retype-policy' in favor of '--migration-policy'

The '--retype-policy' option is used in the 'volume set' command to
specify the migration policy during the retype operation. The
'--retype-policy' option does not convey the correct meaning of its
usage. The migration policy determines whether we are going to perform
the migration in the retype operation or not and is not related to the
actual retype which just changes the volume type of the volume.

Change-Id: I2ea8fd3f5277bb3422ccae915d05e8ad44ff1912

openstackclient/volume/v2/volume.py

@@ -711,6 +711,12 @@ class SetVolume(command.Command):
             '--retype-policy',
             metavar='<retype-policy>',
             choices=['never', 'on-demand'],
+            help=argparse.SUPPRESS,
+        )
+        parser.add_argument(
+            '--migration-policy',
+            metavar='<migration-policy>',
+            choices=['never', 'on-demand'],
             help=_(
                 'Migration policy while re-typing volume '
                 '("never" or "on-demand", default is "never" ) '
@@ -746,6 +752,15 @@ class SetVolume(command.Command):
         volume = utils.find_resource(volume_client.volumes, parsed_args.volume)
 
         result = 0
+        if parsed_args.retype_policy:
+            msg = _(
+                "The '--retype-policy' option has been deprecated in favor "
+                "of '--migration-policy' option. The '--retype-policy' option "
+                "will be removed in a future release. Please use "
+                "'--migration-policy' instead."
+            )
+            self.log.warning(msg)
+
         if parsed_args.size:
             try:
                 if parsed_args.size <= volume.size:
@@ -839,11 +854,12 @@ class SetVolume(command.Command):
                     e,
                 )
                 result += 1
+        policy = parsed_args.migration_policy or parsed_args.retype_policy
         if parsed_args.type:
             # get the migration policy
             migration_policy = 'never'
-            if parsed_args.retype_policy:
+            if policy:
-                migration_policy = parsed_args.retype_policy
+                migration_policy = policy
             try:
                 # find the volume type
                 volume_type = utils.find_resource(
@@ -856,12 +872,14 @@ class SetVolume(command.Command):
             except Exception as e:
                 LOG.error(_("Failed to set volume type: %s"), e)
                 result += 1
-        elif parsed_args.retype_policy:
+        elif policy:
-            # If the "--retype-policy" is specified without "--type"
+            # If the "--migration-policy" is specified without "--type"
             LOG.warning(
-                _(
+                _("'%s' option will not work without '--type' option")
-                    "'--retype-policy' option will not work "
+                % (
-                    "without '--type' option"
+                    '--migration-policy'
+                    if parsed_args.migration_policy
+                    else '--retype-policy'
                 )
             )
 

releasenotes/notes/rename-volume-set-retype-policy-6bacb7dd92f1ad82.yaml

@@ -0,0 +1,8 @@
+---
+upgrade:
+  - |
+    The ``volume set --retype-policy`` parameter has been renamed to
+    ``--migration-policy`` to better convey the correct meaning of the options
+    usage. The migration policy determines whether we are going to perform the
+    migration in the retype opearation or not and is not related to the actual
+    retype which just changes the volume type of the volume.