Azure / service-catalog-cli

See the upstream repository ->
https://github.com/kubernetes-incubator/service-catalog
MIT License
33 stars 14 forks source link

UX is inconsistent with kubectl #25

Closed krancour closed 6 years ago

krancour commented 6 years ago

I'm sure consistency wasn't necessarily a goal, initially, but I want to propose that this UX is so very different from kubectl that it's going to trip people up, and even if it doesn't it's going to annoy them.

svc-cat commands currently take the following form:

$ svc-cat <noun> <verb>

Contrast this to kubectl (which is a very familiar tool to the intended audience):

$ svc-cat <verb> <noun>

Beyond this, I see we're using verbs like get and list. Do we really need to differentiate between those two? kubectl does not. What would stop us from doing this to get all brokers?

$ svc-cat get broker(s)

Get a broker, qualified by name:

$ svc-cat get broker <name>

We also don't need separate subcommands for showing status if status is part of the output when you get something.

In total, I think the following list of commands would suffice for our current purposes and would be closer to what users are already familiar with. (We could start to think of ourselves [for now] like kubectl with nicer, more service catalog specific output.)

I really think this consistency with a familiar tool will win us points with our would-be users. Thoughts?

carolynvs commented 6 years ago

I was thinking the same thing yesterday. 💯 You've got my vote.

carolynvs commented 6 years ago

@krancour How do you see --traverse fitting into this?

arschles commented 6 years ago

I'm ambivalent so I'll look to your instincts on UX. @seanmck can you share your thoughts here?

I would also like to know how --traverse fits in. Maybe svc-cat get bindings --traverse?

krancour commented 6 years ago

What does traverse do? Produces a graph?

arschles commented 6 years ago

Yes. There's discussion inside #22 to possibly default to doing traversal on calls like get bindings

seanmck commented 6 years ago

I agree with @krancour. This is conceptually an extension of kubectl, so it makes sense to align with that paradigm as much as possible.

carolynvs commented 6 years ago

I wanted to clarify how closely we'd like to be consistent with kubectl:

get bindings <name> will retrieve details for single item. It will not act like kubectl which allows advanced filtering like kubectl get deploy/foo svc/bar. Essentially our svc-cat get bindings <name> would work like kubectl describe <name>.

Does that sound right? Or did you want to have a describe command to keep our options open?

krancour commented 6 years ago

@carolynvs good questions. imo, start simple... no need to worry about filtering or partial matches, etc. That can always be added later.

All get (for collections or singular item) should display tabular or row/col data. I would say that if we learn as we go that we can't fit all the useful information into that format, we could consider adding a describe verb after the need for it becomes clear.

carolynvs commented 6 years ago

All get (for collections or singular item) should display tabular or row/col data

I'm glad I asked because the format below is what @arschles and I have been discussing in https://github.com/Azure/service-catalog-cli/issues/4#issuecomment-345798504. I'd prefer to use that for displaying single items, instead of a table with a single result. This is essentially the format of kubectl desribe's output.

svc-cat catalog class get azure-mysqldb --traverse
  Name:          azure-mysqldb
  Description:   Azure Database for MySQL Service
  UUID:          997b8372-8dac-40ac-ae65-758b4a5075a5
  Status:        active
  Tags:          Azure, MySQL, Database

Plans:
     NAME              DESCRIPTION
+-------------+-------------------------+
  standard800    Standard Tier, 800 DTUs
  basic100       Basic Tier, 100 DTUs
  basic50        Basic Tier, 50 DTUs.
  standard200    Standard Tier, 200 DTUs
  standard400    Standard Tier, 400 DTUs
  standard100    Standard Tier, 100 DTUs
krancour commented 6 years ago

@carolynvs I like the format, but here's where I think things get dicey...

Suppose we do (eventually) want to do partial matches like kubectl does. Given existing service classes foobar and foobat, we might expect svc-cat get class foo to return both-- which is why (as with kubectl) I am suggesting that we always use a tabular format for get.

But what you've shown above is very nice... so maybe that's the format for a svc-cat describe class foobar command that will always do a precise name match (no partial match) to guarantee one result.

Any thoughts?

carolynvs commented 6 years ago

Yes, I think we can stay consistent with kubectl without biting off the more advanced features, and leave us room to add them later if there's a need.

krancour commented 6 years ago

@carolynvs that all sgtm.

carolynvs commented 6 years ago

CONSENSUS! ✨ I'm working on a new command for service plans tonight, and will follow these new guidelines. I am closing this and will make a couple issues to tackle bringing our commands in line with what we've agreed upon.