Open Stack

👋

tl;dr: $subject

I reviewed a patch against openstackclient (OSC) today [1] and left a rather
lengthy comment that I thought worthy of bringing up to a wider audience. The
patch itself doesn't matter so much as what is was trying to achieve, namely
modifying an existing OSC command to better match the structure of the
equivalent legacy client command. The review provides more detail than I do here
but the tl;dr: is that this is a big no-no and OSC will and must maintain
consistency between OSC commands over consistency with legacy clients. As I
noted in the review, consistency is one of the biggest advantages of OSC over
the legacy clients: if you know the name of the resource type you wish to work
with, you can pretty accurately guess the command and its structure. This is a
thing that operators have consistently said they love about OSC and its one of
the key reasons we're trying to get every command to provide full current API
implementations in OSC (and SDK).

Now I get that the way some of these consistent commands have been implemented
has been the cause of contention in the past. I don't imagine it remains any
less contentious today. However, these patterns are well-understood, well-known
patterns that have for the most part worked just fine for close to a decade now.
The kind of patterns I'm thinking about include:

 * The command to create a new resource should always take the format
   '<resource> create <human-readable identifer>
 * The command to modify some property of a resource should always take the
   format '<resource> set --property=value <name-or-identifier>'
 * The command to list, fetch or delete resources should always take the format
   '<resource> list', '<resource> get <name-or-identifier>', and '<resource>
   delete <name-or-identifier>', respectively.
 * Boolean options should always take the form of flags with an alternate
   negative option like '--flag' and '--no-flag', rather than '--
   flag=<true|false>'
 * And a couple of other things that we tend to highlight in reviews.

We want to preserve this behavior, lest OSC lose this huge USP and devolve into
a muddle mess of different ideas and various individuals'/teams' preferences.
I'm more than happy to discuss and debate this stuff with anyone who's
interested and we'll continue reviewing each patch on its merit and providing
exceptions to these rules where they make sense, but it will remain an ongoing
goal and it's something we'd like people to consider when working on OSC itself
or any of its plugins.

I will now get off my pedestal/ivory tower 🗼

Thanks!
Stephen

PS: I'm talking here about the command themselves, not their implementations. We
do somethings extra in OSC that are user helpful, like allowing users to
identify resources by their name in addition to by their UUIDs. We also
currently do things that no so user helpful, like crashing and burning if the
name lookups fail (I'm thinking about the various Glance-related commands that
error out if a project name/ID is passed to a command and the user can't look up
that project). These are things we're more than willing to fix and will happily
accept patches for :)

[1] https://review.opendev.org/c/openstack/python-openstackclient/+/865377