From 8bf99f093ded5aff8ee68eca01e85948ee9717a2 Mon Sep 17 00:00:00 2001
From: Drago Rosson <drago@rosson.me>
Date: Tue, 31 Jan 2017 02:40:56 -0600
Subject: [PATCH] Add spec for allowing name as positional argument

blueprint positional-name

Change-Id: I75d14cc3de16810d57424ac9a0f66c7a66982f05
---
 specs/pike/positional-name.rst | 116 +++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 specs/pike/positional-name.rst

diff --git a/specs/pike/positional-name.rst b/specs/pike/positional-name.rst
new file mode 100644
index 0000000..25a119c
--- /dev/null
+++ b/specs/pike/positional-name.rst
@@ -0,0 +1,116 @@
+..
+   This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=================================
+Name as a Positional CLI Argument
+=================================
+
+Launchpad blueprint:
+
+https://blueprints.launchpad.net/magnum/+spec/positional-name
+
+Make the magnum CLI more user-friendly by allowing cluster and cluster template
+names to be specified positionally.
+
+Problem description
+===================
+
+The shortest way to create a cluster using the magnum CLI is::
+
+  magnum cluster-create --cluster-template mytemplate
+
+Since magnum is a service to manage clusters, users will issue sub-commands
+such as `cluster-show`, `cluster-config` `cluster-update`, and
+`cluster-delete`, which all take the form::
+
+  magnum cluster-{command} <name or UUID> ...
+
+If the user didn't specify a name when creating their cluster, they will have
+to use the autogenerated name or the UUID, which are neither personalized nor
+memorable. So, many (or, in my opinion, virtually all) users are going to supply
+a name, which is currently a flag::
+
+  magnum cluster-create --name mycluster --cluster-template mytemplate
+
+The fact that users must specify the name using a flag on create and then
+positionally for all other commands creates a small, but important, amount of
+friction when interacting with magnum; it affects every user creating a
+cluster, reading documentation, or watching a demo about how easy magnum is to
+use.
+
+Names as positional arguments are not unprecedented in OpenStack. In fact,
+there are quite a few resources where the name is positional. For example,
+nova servers and flavors, heat stacks, keystone users, swift containers, and
+neutron networks, security groups, flavors, and routers.
+
+Proposed change
+===============
+
+Support `name` as a positional, optional CLI argument for the `cluster-create`
+and `cluster-template-create` sub-commands::
+
+  magnum cluster-template-create [name] ...
+
+  magnum cluster-create [name] ...
+
+For example::
+
+  magnum cluster-template-create mytemplate ...
+
+  magnum cluster-create mycluster --cluster-template mytemplate ...
+
+Whether `[name]` can appear anywhere in the list of arguments can be
+decided at implementation time. This spec proposes to support the argument at
+least directly after the sub-command name.
+
+Supplying a name will still be optional, and the `--name` flag version of the
+command will still be valid so that all commands are backwards-compatible.
+Whether `[name]` and `--name` are mutually exclusive or one should take
+precedence if both are specified can be decided at implementation time.
+
+This change will not affect the API.
+
+Alternatives
+------------
+
+1. Make name positional and mandatory.
+
+   This would make the magnum CLI more like other OpenStack CLIs where the name
+   is required. However, it would be a breaking CLI change and would probably
+   only make sense if the API were to change too, which would mean it would be
+   a bigger breaking change.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  Jason Dunsmore
+
+Milestones
+----------
+
+Target Milestone for completion:
+  pike-1
+
+Work Items
+----------
+
+1. Support `[name]` for `cluster-create`.
+
+2. Support `[name]` for `cluster-template-create`.
+
+Dependencies
+============
+
+None
+
+Security Impact
+===============
+
+None