Open Stack

For reference, the current list of objects and actions used by commands in
the OSC repo are at
http://docs.openstack.org/developer/python-openstackclient/commands.html.

Also note that while the OSC team may have multiple opinions on what fits
well and does not in plugins, the plugins are owned by the project teams
and not the OSC team and we do not rigidly enforce our structure on
external plugins. Inconsistencies in command structure work against the
entire spirit of why OSC was built to begin with.  For external plugins,
however, we will rely on community feedback to encourage projects to stay
consistent as much as possible.

On Mon, May 25, 2015 at 9:52 AM, Ronald Bradford <me at ronaldbradford.com>
wrote:

> 2. "execute" or "exec"
>
> This is clearly a new type of action that requires OSC to provide
> recommended guidance on. I am 50/50 here.
>

To add a new action I think you need to be clear for the user what it does
and hopefully in a way that is not unique to this command.  Many of the
actions in the docs are specific to servers because they only appear in
server commands.  These can/should be generalized where possible in favor
of adding new actions.

I don't see anything that fits what I would expect an 'execute' action to
do, but then I also don't quite know what this is intended to do.  In the
context of the container command example above, there is execute, start and
stop.  start and stop seem to be create and delete equivalents to the
server commands.  If you choose to deviate from that, you should explain
exactly why and how so the user can figure out the difference.

I don't know what execute does in that context.  Is a container created in
a paused/suspended state?

Also, I'm not a fan of adding yet another set of running state action pairs
(create/delete, pause/unpause, suspend/resume).


> 3. "set" or "update"
>
> While I consider the word "set" to be more an attribute specific term,
> "update" implies a change of multiple attributes. If I just looked at the
> usage I would say "update".  However, looking at the actual usage openstack
> client set syntax uses named parameters to set multiple parameters.
>

Most people's update is OSC's set.  There is also unset for removing an
attribute rather than setting it to a null value.  Set is generally very
similar to create command-wise.


> Looking into the help syntax of a Magnum "update" option, I find it
> supports "add", "replace" and "remove" operations.  This complicates matters
>

We already have the concept of adding and removing resources from other
containing resources.  Look at security groups for the best example.  This
is also one of the only places we use more than one positional parameter,
the rationale being you have two resources in the command itself, both can
be referenced in the args implicitly.


> 4. "service" is already used by Identity. See
> http://docs.openstack.org/developer/python-openstackclient/command-objects/service.html
>
> 5. "container" is already used by Swift. See
> http://docs.openstack.org/developer/python-openstackclient/command-objects/container.html
>

We need to go to multiple word objects here then.  Backward compatibility
gives the bare object name to the existing commands, although I would
suggest we add a qualified object name also: 'service' might become
'catalog service' as an alas.  We document those and ride out a really long
deprecation for something so fundamental.


> I have no suggestions on 4. and 5.
> Given these last 2 entanglements the OSC will quickly become unusable as
> more clients which it integrate.
>

Yup, this is a problem.  We need to anmespace things somehow, be it by
putting the commands into a namespace like congressclient did (all commands
start with 'congress', I'd have suggested not using the project name), or
we namespace the objects as I suggested earlier by using longer and more
specific names.

Or we don't attempt to put the entire big tent client commands into a
single CLI.  There is nothing that says we can't have multiple top-level
commands.  OSC today doesn't easily do that and leverage the existing code
structure, but it probably could if this becomes a popular option.  The
'openstack' command for the usual and common stuff, and a (pulling names
out of my hat here): 'os-tent' for big-tent-related commands (I'm taking
this part literally) and 'os-jewel' for the sparkly, shiny commands that
make brides happy:

os-tent ring create --type elephant dumbo
os-jewel ring create --type wedding sparkle

In the end, the principle of 'least surprise' is important to consider.
And that I still maintain the 'C' in OSC stands for 'Consistent'.

dt


-- 

Dean Troyer
dtroyer at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150526/47948169/attachment.html>