From b99a20720f6cd141a56547533eca13fc64f9d259 Mon Sep 17 00:00:00 2001
From: Steven Kaufer <kaufer@us.ibm.com>
Date: Wed, 7 Jan 2015 17:21:28 +0000
Subject: [PATCH] CLI Sorting Argument Guidelines

This goal of this specification is to define the syntax for client
sorting arguments so that there is consistency across projects.

Note that an API working group guideline for sorting is closely
related:
https://review.openstack.org/#/c/145579/

Change-Id: Id99091cfcf0c8770babba5e6cbf9c9772b015960
---
 specs/cli-sorting-args.rst | 123 +++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 specs/cli-sorting-args.rst

diff --git a/specs/cli-sorting-args.rst b/specs/cli-sorting-args.rst
new file mode 100644
index 0000000..4fe6993
--- /dev/null
+++ b/specs/cli-sorting-args.rst
@@ -0,0 +1,123 @@
+==========================================
+ CLI Sorting Argument Guidelines
+==========================================
+
+To varying degrees, the REST APIs for various projects support sort keys
+and sort directions; these sorting options are exposed as python client
+arguments. This specification defines the syntax for these arguments so
+that there is consistency across clients.
+
+Problem description
+===================
+
+Different projects have implemented the CLI sorting options in different
+ways. For example:
+
+- Nova: --sort key1[:dir1],key2[:dir2]
+- Cinder: --sort_key <key> --sort_dir <dir>
+- Ironic: --sort-key <key> --sort-dir <dir>
+- Neutron: --sort-key <key1> --sort-dir <dir1>
+           --sort-key <key2> --sort-dir <dir2>
+- Glance (under review): --sort-key <key1> --sort-key <key2> --sort-dir <dir>
+
+Proposed change
+===============
+
+Based on mailing list feedback (see References sections), the consensus is to
+follow the syntax that nova currently implements: --sort <key>[:<direction>]
+
+Where the --sort parameter is comma-separated and used to specify one or more
+sort keys and directions. A sort direction is optionally appended to each key
+and is either 'asc' for ascending or 'desc' for descending.
+
+For example:
+
+  * nova list --sort display_name
+  * nova list --sort display_name,vm_state
+  * nova list --sort display_name:asc,vm_state:desc
+  * nova list --sort display_name,vm_state:asc
+
+Unfortunately, the REST APIs for each project support sorting to different
+degrees:
+
+- Nova and Neutron: Multiple sort keys and multiple sort directions
+- Cinder and Ironic: Single sort key and single sort direction (Note: approved
+  kilo spec in Cinder for adding adding for multiple key and direction
+  support)
+- Glance: Multiple sort keys and single sort direction
+
+In the event that the corresponding REST APIs do not support multiple sort
+keys and multiple sort directions, the client may:
+
+- Support a single key and direction
+- Support multiple keys and directions and implement any remaining sorting
+  in the client
+
+Alternatives
+------------
+
+Each sort key and associated direction could be supplied independently, for
+example:
+
+--sort-key key1 --sort-dir dir1 --sort-key key2 --sort-dir dir2
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  * Cinder: Steven Kaufer (kaufer)
+  * Glance: Mike Fedosin (mfedosin)
+
+Work Items
+----------
+
+Cinder:
+  * Deprecate --sort_key and --sort_dir and add support for --sort
+  * Note that the Cinder REST API currently supports only a single sort key
+    and direction so the CLI will have the same restriction, this restriction
+    can be lifted once the following is implemented:
+    https://blueprints.launchpad.net/cinder/+spec/cinder-pagination
+
+Ironic/Neutron:
+  * Deprecate --sort-key and --sort-dir and add support for --sort
+
+Glance:
+  * Modify the existing patch set to adopt the --sort parameter:
+    https://review.openstack.org/#/c/120777/
+  * Note that Glance supports multiple sort keys but only a single sort
+    direction.
+
+
+Dependencies
+============
+
+- Cinder BP for multiple sort keys and directions:
+  https://blueprints.launchpad.net/cinder/+spec/cinder-pagination
+
+History
+=======
+
+.. list-table:: Revisions
+   :header-rows: 1
+
+   * - Release Name
+     - Description
+   * - Kilo
+     - Introduced
+
+References
+==========
+
+- Nova review that implemented the --sort argument:
+  https://review.openstack.org/#/c/117591/
+- Glance client review: https://review.openstack.org/#/c/120777/
+- http://www.mail-archive.com/openstack-dev@lists.openstack.org/msg42854.html
+- http://www.mail-archive.com/openstack-dev%40lists.openstack.org/msg42954.html
+
+.. note::
+
+  This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode