Ddev: Update CLI with standard verbs/nouns and examples

Created on 25 Feb 2017 · 20Comments · Source: drud/ddev

Is this a BUG REPORT or FEATURE REQUEST? (choose one):
Task

What you expected to happen:
Before we build too much more on top of this, we should take a step back and look at the verbs/nouns used in the CLI and ensure the language matches what we want moving forward.

Done criteria:

Example ddev add/stop/start/restart usage for our 3 planned platforms signed off on by @rickmanelius ( #2, https://github.com/drud/general/issues/71)
Update CLI to reflect chosen verbs/nouns and usage examples should be updated and accurate for all commands
running just ddev without arguments should print help
[stretch] Example config commands for our 3 planned platforms.

Testing strategy

Ensure ddev prints help.

27

actionable

Source

beeradb

Most helpful comment

Notes from 2017-03-13

The team (Brad, Kevin, Randy, Chris, Tanner, and myself) met today to review the proposed changes. Here are the notable outcomes and summarized future state for 0.2.

Outcomes

Here are a list of decisions:

We will stick to “start”, “stop”, and “restart” terminology.
Command “start” will do double duty. If containers specified in the YAML configuration file are not present, “start” will download and place in the appropriate location.
We will remove the “update” command. Instead, “version” will notify users if their current version is out of date along with a link to instructions on how to obtain and install the latest binary.
We will leave “exec” for now, and potentially alias in the future if it makes sense.
We will remove “sequelpro” for now in order to make sure we don’t pollute the top level namespace with services that might not be relevant to the specific app. While these can be convenient, we need to create a better strategy that is more generic. For now, the information will be available in the “describe” command. In the future, we may opt to reintroduce these shortcuts under an appropriate namespace (e.g. “services” or “shortcuts”).
Command “config” will be specific to the individual application. Once the “legacy” plugin was removed, most of the needs surrounding global configuration were removed. We can revisit in the future if/when necessary.
Command “workon” will be removed for now given work already being performed at the workspace level.
Placeholder: If we proceed with a “rebuild”, it will likely be a combination of “remove” and “start”. * While we could arguably do an import as well to bring an app back to state, for now we’ll rely on the end-user to use a follow-up “import” command.

Here are a list of next actions:

File an issue to remove the “update” command.
File an issue to remove the “sequelpro” command.
File an issue to remove the “workon” command (this may already exist in another ticket).
Clarify the intention of the “import” command to prompt the user before destroying the current database and files while leaving the git history in place.

Future State v0.2

config: Set or view ddev configurations.
exec: Run a command in the specified app container.
describe: Prints metadata of app and local services.
hostname: Manage your hostfile entries.
import: Replace an app's codebase, database, and file structure.
list: List applications that exist locally.
restart: Stop and Start an app's local services.
remove: Remove an app's local services.
ssh: SSH to an app container.
start: Start an app's local services.
stop: Stop an app's local services.
version: print ddev's version and component versions

rickmanelius on 13 Mar 2017

👍4

All 20 comments

As discussed. There are 4 parts

Choose Nouns/Verbs (this will likely require a quick convo w/several stakeholders, probably Erin, Chris, Tanner, and Rick).
Implement
Examples
Help

rickmanelius on 27 Feb 2017

I don't mind the current verbs/nouns. I am biased though.

frodopwns on 27 Feb 2017

Over in https://github.com/drud/ddev/pull/52 @tannerjfco has already split 'add' into 'start' and 'import', which seems like a good thing. IMO there are probably 3 logical parts of the former 'add', 'init' (tell it what kind of site and what the name of the thing is - equivalent of 'init' in vagrant world, or writing-a-config-file in the docker world), 'start' (start up the containers so they can work, equivalent of 'up' in the vagrant world or 'start' in the docker world), 'import', where you pull in resources like db from some external source.

rfay on 9 Mar 2017

I'll cross-post in #52, but we had decided on config over init, as the thought was you could re-run config and it would auto-fill with the existing config (if you needed to change something)

beeradb on 9 Mar 2017

The only problem I have with 'config' is it seems to imply global configuration. But if we aren't using global configuration it might be fine.

rfay on 9 Mar 2017

Great point. I don't think we considered the global config command when deciding on that word.

beeradb on 9 Mar 2017

We need some real help quickly on this @rickmanelius - Already the start/stop that devs have used is changing meaning in https://github.com/drud/ddev/pull/52. As I understand, devs used start/stop to manage resources on their machine in order to have only the containers for the most current sites running. Then config is in play in https://github.com/drud/ddev/issues/57 - possibly the key issue with config is that we are switching from a global idea of "config" to a site-specific localized config.

Note that https://github.com/drud/ddev/pull/58 completely removes the traditional/global idea o config.

There is not much risk in choosing the wrong words here, the problem is choosing the wrong semantics. It's easy to alias commands, it's fairly easy to change the primary name for a command. But if we don't get logical abstractions (regardless of the words) that resonate with devs, then we do have a problem.

rfay on 10 Mar 2017

I can take a peek after stand-up today.

rickmanelius on 10 Mar 2017

As of commit https://github.com/drud/ddev/tree/06ac3b28f2a429ece86cb39e35d50d0c5ee5c94a on master (updated yesterday), running ddev without any flags outputs all available commands. The current inventory of nouns/verbs stands as the following:

add: Add an existing application to your local development environment
config: Set or view DRUD configurations.
exec: run a command in an app container.
hostname: Manage your hostfile entries.
list: List applications that exist locally
logs: Get the logs from your running services.
restart: Stop and Start the app.
rm: Remove an application's local services.
sequelpro: Easily connect local site to sequelpro
ssh: SSH to an app container.
start: Start an application's local services.
stop: Stop an application's local services.
update: Update DRUD cli tool
version: print ddev version and component versions
workon: Set a site to work on

I'm going to move this analysis to a google doc for now and (once completed) post summary back to this thread.

rickmanelius on 10 Mar 2017

As per https://github.com/drud/ddev/pull/52, there is an additional command "import" as part of replacing "add" in favor of "import" and "start".

import: Import the database and file assets of an existing site into the local development environment.

rickmanelius on 10 Mar 2017

In order to answer this, I think it makes back to step back and focus on the intentions of an end-user and that will inform the inventory and selection of words. Broadly, we see things categorized into the following categories.

Compound: Commands that combine multiple other commands into one based on a frequent task. Example: "restart" = stop + start.
Shortcuts: Commands that provide a shortcut to a service that could be otherwise obtained through other means. Example: sequelpro. This could likely become a very long list as we add more tools and services. We may want to abstract this away to a general "services" command that shows all services for a project.
Configuration: Commands that modify global and project specific information. Examples include "workon" and "hostmane".
Workflow: Commands that users use to engage the specified projects. Examples include start, stop, exec.
Project Management: Commands that allow the addition or removal of assets being used by ddev. Examples include import, rm, and configuration.
ddev Management: Commands that provide information related to ddev itself, including "version" and "uprade".

Given this breakdown, there are areas that get a little blurry. For example, let's say I'm an end-user trying to get an archive up and running. In an ideal world, there would be a shortcut (similar to what we're discussing with platform plugin) where we could just point at an archive that would unzip, place into the appropriate folder, and get a project configuration in place. In a more manual approach, there would be distinct steps to do each.

We also want to make sure we have parity. If there is a command that pulls files in (import) there should be one that removes them (rm). There may in fact be a use case to create a shortcut (rm, import, and config). If we look outward toward the experiences of other tools, we see this as a "rebuild", and that command would probably have different ways of importing based on the type of provider pluging it is.

As noted earlier in this thread, there is a possible pain point surrounding the tripled duty that "config" is handling. We are using it to both add and update the projects configuration. Alternatively, it could update a global ddev configuration.

This is a bit rambly, but I think it boils down to 4 things:

Easy Items:

Renaming: Situations where the end-user intention is exact (e.g. start and stop) but we may wish to adopt terminology that is more consistent with other products or experiences (e.g. up and down to match vagrant).
Clean-up: Situations where the end-user intention is exact, but we just want to make the descriptions more precise. This might also
Missing Items: Stubbed out requests for commands we already wanted to include (describe) and commands that we may want to optimize and/or combine (rebuild).

Harder Items:

Semantic items: This seems to be related to commands that are potentially doing the wrong thing or too many things. It seems like the only area that is questionable is "config".

Given that items 1-3 should be addressable through a search & replace or an alias, the biggest issue is #4. This will require a little more thought because I like the idea of the configuration handling both the initial config file generate and update, but we still need a way to handle the global configuration (which I believe is useful and shouldn't be dropped).

rickmanelius on 10 Mar 2017

Initial recommendations

Terminology Only

These are largely naming conventions and do not effect the current functionality or intention behind the words.

Regarding start/stop/restart, I think these are prefered over up/down (despite their use in Vagrant's terminology). Restart builds off of start, and the best alternative is "reload", which I generally don't like as much because it could also imply "loading" or "importing". We can still create 2 letter aliases off of start/stop for convenience.
exec is nice, but I did like how Kalabox created a short "." command. Might be worth considering as an alias.
update => upgrade. Upgrade is more specific to the intention of upgrading ddev. Update could mean other things: update configuration, provide an update on a request, etc.

Bigger Discussions

Services: Given the number of services that can be available (and some of them are app specific because they depend on the containers specified in the configuration file), it might make sense to namespace them underneath services. Things like sequelpro, phpmyadmin could git here.
Config: Services like Kalabox (http://docs.kalabox.io/en/stable/users/cli/#config) conflate the two and will simply append global configuration to a local app's configuration if the command is run. I feel strongly that using configure to add/edit an app's configuration makes the most sense, and we can rely on one of 4 ways to adjust ddev's global settings: stand-along functions (workon), manually editing the file, initial install wizard the first time ddev is run (if configuration file doesn't exist), or a "config-global" or "global" command to update global settings. For now, the first 2 seem sufficient with the 3rd and 4th options being more relevant in the future.
Create: This should be a function in the future to create an application from a template from a plugin. This could be "ddev create drud drupal7" or "ddev create pantheon drupal7", for example.
Rebuild: While we have the concept of restart (essentially stop => start), we don't have the concept of a "rebuild". I could imagine this as a remove (or because this is drud... "destroy"?) followed by a "start" and an "import". From a parity perspective, does it make sense to have a companion to "import"? What if I wanted to rebuild not by throwing away all containers but by deleting and re-importing the files/code/db? It's worth noting that ddev alternatives do not really focus on how to important from a non-platform plugin and don't appear to provide a way to pull in a project from a rebuild.

rickmanelius on 13 Mar 2017

Notes from 2017-03-13

The team (Brad, Kevin, Randy, Chris, Tanner, and myself) met today to review the proposed changes. Here are the notable outcomes and summarized future state for 0.2.

Outcomes

Here are a list of decisions:

We will stick to “start”, “stop”, and “restart” terminology.
Command “start” will do double duty. If containers specified in the YAML configuration file are not present, “start” will download and place in the appropriate location.
We will remove the “update” command. Instead, “version” will notify users if their current version is out of date along with a link to instructions on how to obtain and install the latest binary.
We will leave “exec” for now, and potentially alias in the future if it makes sense.
We will remove “sequelpro” for now in order to make sure we don’t pollute the top level namespace with services that might not be relevant to the specific app. While these can be convenient, we need to create a better strategy that is more generic. For now, the information will be available in the “describe” command. In the future, we may opt to reintroduce these shortcuts under an appropriate namespace (e.g. “services” or “shortcuts”).
Command “config” will be specific to the individual application. Once the “legacy” plugin was removed, most of the needs surrounding global configuration were removed. We can revisit in the future if/when necessary.
Command “workon” will be removed for now given work already being performed at the workspace level.
Placeholder: If we proceed with a “rebuild”, it will likely be a combination of “remove” and “start”. * While we could arguably do an import as well to bring an app back to state, for now we’ll rely on the end-user to use a follow-up “import” command.

Here are a list of next actions:

File an issue to remove the “update” command.
File an issue to remove the “sequelpro” command.
File an issue to remove the “workon” command (this may already exist in another ticket).
Clarify the intention of the “import” command to prompt the user before destroying the current database and files while leaving the git history in place.

Future State v0.2

config: Set or view ddev configurations.
exec: Run a command in the specified app container.
describe: Prints metadata of app and local services.
hostname: Manage your hostfile entries.
import: Replace an app's codebase, database, and file structure.
list: List applications that exist locally.
restart: Stop and Start an app's local services.
remove: Remove an app's local services.
ssh: SSH to an app container.
start: Start an app's local services.
stop: Stop an app's local services.
version: print ddev's version and component versions

rickmanelius on 13 Mar 2017

👍4

@cyberswat I moving to needs review (previous comment should be the final summary) and leaving it up to you who would be appropriate to tag for that. Once approved with no major changes, we can close this out and create the suggested tickets listed above. Moving on for now!

rickmanelius on 13 Mar 2017

@rickmanelius this is looking good. Do you want to create the new tickets so that this issue can be closed?