(design_proposal): chef cli catalog

[afiune]

Description

A design proposal for the future of the chef CLI Catalog.

Motivation

As a Chef Operator,
I need a unified Command Line Interface (CLI) that lets me interact with every Chef product,
so I can easly discover the capabilities of the Chef ecosystem.

As a Chef Developer,
I need to be able to gather information about how our users consume and interact with our tools,
so I can identify which commands are used the most and measure the usability and performance on all supported platforms.

Acceptance Criteria

• A design doc is stored inside the code repo
• The design doc has been approved by everyone on the team
• Design doc has enough details / shared understanding that any engineer could write correctly scoped cards based on it
• Update the linked epic card to capture the scope of this design

Signed-off-by: Salim Afiune afiune@chef.io

[jonsmorrow]

Overall I like the general idea and shape here. Anytime we do design proposals we want to be able to defend questions like:
What other solutions to this problem where considered?
Are there simpler options or steps along the way that provide value and help us evaluate the path?

I think we can work on the problem statement and it will help with these.

What jumps out to me is a more measured approach where we get telemetry into each of these commands. At least enough to know when they are called. This might influence how/if we brig something under the top level chef command. We could do this with go wrappers and a go telemetry library or maybe look at the ruby bins already generated and see if we can insert the existing library.

[jonsmorrow]

Chef Operator to bring this in-line with our current target user base.

[jonsmorrow]

All of the other goals are more tangible. I'd say something like: "Consistent/Usable performance on all supported platforms"

[jonsmorrow]

This so states things you could do not why you'd want to. Is there a way to say this without talking about extreme changes. Anytime we use that kind of language it can alienate folks that want more measured changed/no change. It's ok if you really mean to drive extreme change and understand the above, but make sure that's the intent.

[jonsmorrow]

These I woulds are future tense assuming this has been implemented. I think they need to be written as what is desired. It's also pre-judging the architecture before garnering feedback. I'd suggest more along the lines of: I would like a more flexible architecture that allows me to invest in improvements selectively where they will have the most impact.

[jonsmorrow]

It's been there longer, so I'd find when it landed or just remove the version.

[afiune]

yup, since 0.10.41

[jonsmorrow]

wrapper around chef commands.

[jyan-chef]

is it correct to assume the wrapper has been applied to all commands for all binaries included in workstation?

[jonsmorrow]

Here you are future tense again as if it's been done. I think you want to say something like this design proposes we expand this scope to be a proxy/catalog of all the user facing cli tools we ship.

[jonsmorrow]

s/we are now able/we would be able

[jonsmorrow]

~10 minutes a day from our users waiting for value.

[jyan-chef]

Can someone help me understand how catalog improvements are links to performance? (i.e. how does the catalog work speeds things up)

[jonsmorrow]

Can we do this in a non-aggressive way?

[jyan-chef]

With regard to telemetry, how can we link this to legal requirements around data capture so the design doc includes the our internal privacy requirements? (e.g. how can we log requirements from legal such as only turn on anonymous data capture after accepting the EULA?)

[jyan-chef]

Just FYI, there's some dependency here on business requirements and legal requirements. Essentially we need to solidify our business requirements, get buy in from potential stakeholders (i.e. outside of Prod/Eng) and then get legal approval to proceed. This work is essential but just want to call out that the requirements are a little TBD right now and we have legal hurdles to overcome.

[jyan-chef]

I think having a catalog of all available commands/tools is very important. Once the user becomes aware of a tool, the next step is really for them to figure out what it does and if it's useful to them. Is that part of the intended scope of this work? If so then we can collaborate w/ UX team on figuring where/how to display relevant information about each tool and maybe include URLs to more detailed information (e.g. docs page) to users

[afiune]

Yes, this is exactly one of the ideas/goals and therefore, collaboration with UX will be required.

[jonsmorrow]

Jon will take point on driving this with Jessica and coordinating with salim for any updates to the design.

[tyler-ball]

IMO, we should not communicate the existence of these binaries to users but we should not prevent their usage. It is just unsupported usage.

[tyler-ball]

I misunderstood this line - I was thinking that we should document chef policy and not document chef-policy but if they run chef-policy we don't do anything to prevent them from doing that.

[tyler-ball]

Going with the CLI UX noun verb guidelines I think the following make more sense:

chef policy install
chef policy update
chef policy push
chef policy show
chef policy diff
chef policy export
chef policy delete
chef policy undelete
chef policy-archive push
chef policy-cookbooks clean
chef policy-group delete
chef policy-revisions clean

Under the covers, chef policy-group delete could still invoke chef-policy group delete but that would be an internal implementation detail. It would make it easier for us to implement because it would be less changing of existing code. But I think the public contract is more important to cover in this design doc than the internal implementation of our command routing.

Thoughts?

[afiune]

From our conversation over zoom we have agreed that these commands look correct with the exception of chef-policy push-archive that will be removed and include into the chef-policy push command.

[tyler-ball]

More context - I convinced myself that switching to a strictly enforced 'noun verb' syntax means we end up with a bunch of unnecessary nouns (policy-revision, policy-cookbooks, policy-groups, etc.) with 1 verb each.

Instead we talked over some of the existing commands and think the PR correctly documents them. The 'noun' in this case is always 'policy' because all these commands are all connected to Policyfiles.

The only tricky one is chef-policy clean cookbooks because it deletes cookbooks that are not referenced by a policyfile. Maybe this becomes an alias for something like chef cookbooks clean?

[tyler-ball]

Talked with Salim about this - IMO, our first implementation should reference chef policy in all the help text. This makes it more confusing for our effortless developers who will directly invoke the chef-policy binary (without all the overhead of the entire Chef Workstation ecosystem). But those are internal users we can help.

In the future I could see us developing a Golang effortless executable that functions similarly to the chef golang executable. It allows us to start creating a custom workflow for them, leveraging tools under the covers that they do not care whether are written in Ruby or Golang. At that time I would introduce some kind of environment variable that would allow the help text to display chef policy or effortless policy.

[tyler-ball]

Notes from group discussion: We want to add "auto-generated docs for tools/products" to the goals for this proposal.

[tyler-ball]

now is unnecessary, can just say Use

[jonsmorrow]

There's additional spin off work to clarify the specific implementation, but this architecture and general direction looks good.

[afiune]