Merge pull request #509 from chris-crone/ux-cleanup

simonferquel · web-flow · commit 543a5a206cdc · 2019-04-18T13:01:40.000+02:00
Clean up command help and flags
diff --git a/cmd/cnab-run/main.go b/cmd/cnab-run/main.go
@@ -38,7 +38,7 @@ func getCnabAction() (cnabAction, string, error) {
 func main() {
 	action, actionName, err := getCnabAction()
 	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error while parsing cnab operation: %s", err)
+		fmt.Fprintf(os.Stderr, "Error while parsing CNAB operation: %s", err)
 		os.Exit(1)
 	}
 	instanceName := os.Getenv("CNAB_INSTALLATION_NAME")
diff --git a/e2e/commands_test.go b/e2e/commands_test.go
@@ -60,7 +60,7 @@ func testRenderApp(appPath string, env ...string) func(*testing.T) {
 		data, err := ioutil.ReadFile(filepath.Join(appPath, "env.yml"))
 		assert.NilError(t, err)
 		assert.NilError(t, yaml.Unmarshal(data, &envParameters))
-		args := dockerCli.Command("app", "render", filepath.Join(appPath, "my.dockerapp"), "--parameters-files", filepath.Join(appPath, "parameters-0.yml"))
+		args := dockerCli.Command("app", "render", filepath.Join(appPath, "my.dockerapp"), "--parameters-file", filepath.Join(appPath, "parameters-0.yml"))
 		for k, v := range envParameters {
 			args = append(args, "--set", fmt.Sprintf("%s=%s", k, v))
 		}
diff --git a/e2e/plugin_test.go b/e2e/plugin_test.go
@@ -15,7 +15,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
 	// docker --help should list app as a top command
 	cmd.Command = dockerCli.Command("--help")
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
-		Out: "app*        Docker Application Packages (Docker Inc.,",
+		Out: "app*        Docker Application (Docker Inc.,",
 	})
 
 	// docker app --help prints docker-app help
@@ -30,7 +30,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
 
 	// docker info should print app version and short description
 	cmd.Command = dockerCli.Command("info")
-	re := regexp.MustCompile(`app: Docker Application Packages \(Docker Inc\., .*\)`)
+	re := regexp.MustCompile(`app: Docker Application \(Docker Inc\., .*\)`)
 	output := icmd.RunCmd(cmd).Assert(t, icmd.Success).Combined()
 	assert.Assert(t, re.MatchString(output))
 }
diff --git a/e2e/testdata/plugin-usage-experimental.golden b/e2e/testdata/plugin-usage-experimental.golden
@@ -1,20 +1,20 @@
 
 Usage:	docker app COMMAND
 
-Build and deploy Docker Application Packages.
+A tool to build and manage Docker Applications.
 
 Commands:
-  bundle      Create a CNAB invocation image and bundle.json for the application
+  bundle      Create a CNAB invocation image and `bundle.json` for the application
   completion  Generates completion scripts for the specified shell (bash or zsh)
-  init        Start building a Docker application
-  inspect     Shows metadata, parameters and a summary of the compose file for a given application
+  init        Initialize Docker Application definition
+  inspect     Shows metadata, parameters and a summary of the Compose file for a given application
   install     Install an application
-  merge       Merge a multi-file application into a single file
-  pull        Pull an application from a registry
-  push        Push the application to a registry
-  render      Render the Compose file for the application
-  split       Split a single-file application into multiple files
-  status      Get the installation status. If the installation is a docker application, the status shows the stack services.
+  merge       Merge a directory format Docker Application definition into a single file
+  pull        Pull an application package from a registry
+  push        Push an application package to a registry
+  render      Render the Compose file for an Application Package
+  split       Split a single-file Docker Application definition into the directory format
+  status      Get the installation status of an application
   uninstall   Uninstall an application
   upgrade     Upgrade an installed application
   validate    Checks the rendered application is syntactically correct
diff --git a/e2e/testdata/plugin-usage.golden b/e2e/testdata/plugin-usage.golden
@@ -1,20 +1,20 @@
 
 Usage:	docker app COMMAND
 
-Build and deploy Docker Application Packages.
+A tool to build and manage Docker Applications.
 
 Commands:
-  bundle      Create a CNAB invocation image and bundle.json for the application
+  bundle      Create a CNAB invocation image and `bundle.json` for the application
   completion  Generates completion scripts for the specified shell (bash or zsh)
-  init        Start building a Docker application
-  inspect     Shows metadata, parameters and a summary of the compose file for a given application
+  init        Initialize Docker Application definition
+  inspect     Shows metadata, parameters and a summary of the Compose file for a given application
   install     Install an application
-  merge       Merge a multi-file application into a single file
-  pull        Pull an application from a registry
-  push        Push the application to a registry
-  render      Render the Compose file for the application
-  split       Split a single-file application into multiple files
-  status      Get the installation status. If the installation is a docker application, the status shows the stack services.
+  merge       Merge a directory format Docker Application definition into a single file
+  pull        Pull an application package from a registry
+  push        Push an application package to a registry
+  render      Render the Compose file for an Application Package
+  split       Split a single-file Docker Application definition into the directory format
+  status      Get the installation status of an application
   uninstall   Uninstall an application
   upgrade     Upgrade an installed application
   validate    Checks the rendered application is syntactically correct
diff --git a/examples/voting-app/Makefile b/examples/voting-app/Makefile
@@ -24,11 +24,11 @@ cleanup: cleanup/production cleanup/development
 #
 render/production: cleanup/production
 	@mkdir -p $(PRODUCTION_DIR)
-	docker-app render --parameters-files $(PARAMETERS_DIR)/production.yml > $(PRODUCTION_DIR)/docker-compose.yml
+	docker-app render --parameters-file $(PARAMETERS_DIR)/production.yml > $(PRODUCTION_DIR)/docker-compose.yml
 
 render/development: cleanup/development
 	@mkdir -p $(DEVELOPMENT_DIR)
-	docker-app render --parameters-files $(PARAMETERS_DIR)/development.yml > $(DEVELOPMENT_DIR)/docker-compose.yml
+	docker-app render --parameters-file $(PARAMETERS_DIR)/development.yml > $(DEVELOPMENT_DIR)/docker-compose.yml
 
 render: render/production render/development
 
@@ -47,10 +47,10 @@ stop: stop/production stop/development
 # Deploy.
 #
 deploy/production: render/production stop/production
-	docker-app deploy --parameters-files $(PARAMETERS_DIR)/production.yml
+	docker-app deploy --parameters-file $(PARAMETERS_DIR)/production.yml
 
 deploy/development: render/development stop/development
-	docker-app deploy --parameters-files $(PARAMETERS_DIR)/development.yml
+	docker-app deploy --parameters-file $(PARAMETERS_DIR)/development.yml
 
 #
 # Pack.
diff --git a/examples/wordpress/README.md b/examples/wordpress/README.md
@@ -54,7 +54,7 @@ volumes:
 **Override default parameters with file**. This example sets `debug` to `"false"` and the wordpress service published port to 80 as defined in `prod-parameters.yml`.
 
 ```yaml
-# docker-app render wordpress --parameters-files prod-parameters.yml
+# docker-app render wordpress --parameters-file prod-parameters.yml
 version: "3.6"
 [...]
     environment:
diff --git a/internal/commands/bundle.go b/internal/commands/bundle.go
@@ -28,15 +28,16 @@ type bundleOptions struct {
 func bundleCmd(dockerCli command.Cli) *cobra.Command {
 	var opts bundleOptions
 	cmd := &cobra.Command{
-		Use:   "bundle [<app-name>]",
-		Short: "Create a CNAB invocation image and bundle.json for the application",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "bundle [APP_NAME] [--output OUTPUT_FILE]",
+		Short:   "Create a CNAB invocation image and `bundle.json` for the application",
+		Example: `$ docker app bundle myapp.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runBundle(dockerCli, firstOrEmpty(args), opts)
 		},
 	}
 
-	cmd.Flags().StringVarP(&opts.out, "output", "o", "bundle.json", "path to the output bundle.json (- for stdout)")
+	cmd.Flags().StringVarP(&opts.out, "output", "o", "bundle.json", "Output file (- for stdout)")
 	return cmd
 }
 
diff --git a/internal/commands/completion.go b/internal/commands/completion.go
@@ -14,19 +14,20 @@ func completionCmd(dockerCli command.Cli, rootCmd *cobra.Command) *cobra.Command
 	return &cobra.Command{
 		Use:   "completion SHELL",
 		Short: "Generates completion scripts for the specified shell (bash or zsh)",
-		Long: `# Load the docker-app completion code for bash into the current shell
-. <(docker-app completion bash)
-# Set the docker-app completion code for bash to autoload on startup in your ~/.bashrc,
+		Long: `# Load the "docker app" completion code for bash into the current shell
+. <(docker app completion bash)
+# Set the "docker app" completion code for bash to autoload on startup in your ~/.bashrc,
 # ~/.profile or ~/.bash_profile
-. <(docker-app completion bash)
+. <(docker app completion bash)
 # Note: bash-completion is needed.
 
-# Load the docker-app completion code for zsh into the current shell
-source <(docker-app completion zsh)
-# Set the docker-app completion code for zsh to autoload on startup in your ~/.zshrc
-source <(docker-app completion zsh)
+# Load the "docker app" completion code for zsh into the current shell
+source <(docker app completion zsh)
+# Set the "docker app" completion code for zsh to autoload on startup in your ~/.zshrc,
+source <(docker app completion zsh)
 `,
-		Args: cli.RequiresMaxArgs(1),
+		Example: `$ . <(docker app completion bash)`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			switch {
 			case len(args) == 0:
diff --git a/internal/commands/init.go b/internal/commands/init.go
@@ -15,17 +15,18 @@ var (
 
 func initCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "init <app-name> [-c <compose-file>] [-d <description>] [-m name:email ...]",
-		Short: "Start building a Docker application",
-		Long:  `Start building a Docker application. Will automatically detect a docker-compose.yml file in the current directory.`,
-		Args:  cli.ExactArgs(1),
+		Use:     "init APP_NAME [--compose-file COMPOSE_FILE] [--description DESCRIPTION] [--maintainer NAME:EMAIL ...] [OPTIONS]",
+		Short:   "Initialize Docker Application definition",
+		Long:    `Start building a Docker Application package. If there is a docker-compose.yml file in the current directory it will be copied and used.`,
+		Example: `$ docker app init myapp --description "a useful description"`,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return packager.Init(args[0], initComposeFile, initDescription, initMaintainers, initSingleFile)
 		},
 	}
-	cmd.Flags().StringVarP(&initComposeFile, "compose-file", "c", "", "Initial Compose file (optional)")
-	cmd.Flags().StringVarP(&initDescription, "description", "d", "", "Initial description (optional)")
-	cmd.Flags().StringArrayVarP(&initMaintainers, "maintainer", "m", []string{}, "Maintainer (name:email) (optional)")
-	cmd.Flags().BoolVarP(&initSingleFile, "single-file", "s", false, "Create a single-file application")
+	cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use as application base (optional)")
+	cmd.Flags().StringVar(&initDescription, "description", "", "Human readable description of your application (optional)")
+	cmd.Flags().StringArrayVar(&initMaintainers, "maintainer", []string{}, "Name and email address of person responsible for the application (name:email) (optional)")
+	cmd.Flags().BoolVar(&initSingleFile, "single-file", false, "Create a single-file Docker Application definition")
 	return cmd
 }
diff --git a/internal/commands/inspect.go b/internal/commands/inspect.go
@@ -18,9 +18,10 @@ type inspectOptions struct {
 func inspectCmd(dockerCli command.Cli) *cobra.Command {
 	var opts inspectOptions
 	cmd := &cobra.Command{
-		Use:   "inspect [<app-name>] [-s key=value...] [-f parameters-file...]",
-		Short: "Shows metadata, parameters and a summary of the compose file for a given application",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "inspect [APP_NAME] [OPTIONS]",
+		Short:   "Shows metadata, parameters and a summary of the Compose file for a given application",
+		Example: `$ docker app inspect myapp.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInspect(dockerCli, firstOrEmpty(args), opts)
 		},
diff --git a/internal/commands/install.go b/internal/commands/install.go
@@ -31,22 +31,25 @@ const (
 	nameKindReference
 )
 
-const longDescription = `Install the application on either Swarm or Kubernetes.
-Bundle name is optional, and can:
-- be empty and resolve to any *.dockerapp in working directory
-- be a BUNDLE file path and resolve to any *.dockerapp file or dir, or any CNAB file (signed or unsigned)
-- match a bundle name in the local bundle repository
-- refer to a CNAB in a container registry
-`
+const longDescription = `Install an application.
+By default, the application definition in the current directory will be
+installed. The APP_NAME can also be:
+- a path to a Docker Application definition (.dockerapp) or a CNAB bundle.json
+- a registry Application Package reference`
+
+const example = `$ docker app install myapp.dockerapp --name myinstallation --target-context=mycontext
+$ docker app install myrepo/myapp:mytag --name myinstallation --target-context=mycontext
+$ docker app install bundle.json --name myinstallation --credential-set=mycredentials.yml`
 
 func installCmd(dockerCli command.Cli) *cobra.Command {
 	var opts installOptions
 
 	cmd := &cobra.Command{
-		Use:     "install [<bundle name>] [OPTIONS]",
+		Use:     "install [APP_NAME] [--name INSTALLATION_NAME] [--target-context TARGET_CONTEXT] [OPTIONS]",
 		Aliases: []string{"deploy"},
 		Short:   "Install an application",
 		Long:    longDescription,
+		Example: example,
 		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInstall(dockerCli, firstOrEmpty(args), opts)
@@ -56,7 +59,7 @@ func installCmd(dockerCli command.Cli) *cobra.Command {
 	opts.credentialOptions.addFlags(cmd.Flags())
 	opts.registryOptions.addFlags(cmd.Flags())
 	opts.pullOptions.addFlags(cmd.Flags())
-	cmd.Flags().StringVarP(&opts.orchestrator, "orchestrator", "o", "", "Orchestrator to install on (swarm, kubernetes)")
+	cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to install on (swarm, kubernetes)")
 	cmd.Flags().StringVar(&opts.kubeNamespace, "kubernetes-namespace", "default", "Kubernetes namespace to install into")
 	cmd.Flags().StringVar(&opts.stackName, "name", "", "Installation name (defaults to application name)")
 
diff --git a/internal/commands/merge.go b/internal/commands/merge.go
@@ -61,9 +61,10 @@ func removeAndRename(source, target string) error {
 
 func mergeCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "merge [<app-name>] [-o output_file]",
-		Short: "Merge a multi-file application into a single file",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "merge [APP_NAME] [--output OUTPUT_FILE]",
+		Short:   "Merge a directory format Docker Application definition into a single file",
+		Example: `$ docker app merge myapp.dockerapp --output myapp-single.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			extractedApp, err := packager.Extract(firstOrEmpty(args))
 			if err != nil {
diff --git a/internal/commands/pull.go b/internal/commands/pull.go
@@ -15,9 +15,10 @@ import (
 func pullCmd(dockerCli command.Cli) *cobra.Command {
 	var opts registryOptions
 	cmd := &cobra.Command{
-		Use:   "pull <repotag>",
-		Short: "Pull an application from a registry",
-		Args:  cli.ExactArgs(1),
+		Use:     "pull NAME:TAG [OPTIONS]",
+		Short:   "Pull an application package from a registry",
+		Example: `$ docker app pull docker/app-example:0.1.0`,
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPull(dockerCli, args[0], opts)
 		},
diff --git a/internal/commands/push.go b/internal/commands/push.go
@@ -34,9 +34,10 @@ type pushOptions struct {
 func pushCmd(dockerCli command.Cli) *cobra.Command {
 	var opts pushOptions
 	cmd := &cobra.Command{
-		Use:   "push [<app-name>]",
-		Short: "Push the application to a registry",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "push [APP_NAME] --tag TARGET_REFERENCE [OPTIONS]",
+		Short:   "Push an application package to a registry",
+		Example: `$ docker app push myapp --tag myrepo/myapp:mytag`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPush(dockerCli, firstOrEmpty(args), opts)
 		},
diff --git a/internal/commands/render.go b/internal/commands/render.go
@@ -23,10 +23,10 @@ type renderOptions struct {
 func renderCmd(dockerCli command.Cli) *cobra.Command {
 	var opts renderOptions
 	cmd := &cobra.Command{
-		Use:   "render <app-name> [-s key=value...] [-f parameters-file...]",
-		Short: "Render the Compose file for the application",
-		Long:  `Render the Compose file for the application.`,
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "render [APP_NAME] [--set KEY=VALUE ...] [--parameters-file PARAMETERS-FILE ...] [OPTIONS]",
+		Short:   "Render the Compose file for an Application Package",
+		Example: `$ docker app render myapp.dockerapp --set key=value`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runRender(dockerCli, firstOrEmpty(args), opts)
 		},
diff --git a/internal/commands/root.go b/internal/commands/root.go
@@ -13,8 +13,8 @@ import (
 // NewRootCmd returns the base root command.
 func NewRootCmd(use string, dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Short: "Docker Application Packages",
-		Long:  `Build and deploy Docker Application Packages.`,
+		Short: "Docker Application",
+		Long:  `A tool to build and manage Docker Applications.`,
 		Use:   use,
 	}
 	addCommands(cmd, dockerCli)
@@ -83,8 +83,8 @@ type parametersOptions struct {
 }
 
 func (o *parametersOptions) addFlags(flags *pflag.FlagSet) {
-	flags.StringArrayVarP(&o.parametersFiles, "parameters-files", "f", []string{}, "Override parameters files")
-	flags.StringArrayVarP(&o.overrides, "set", "s", []string{}, "Override parameters values")
+	flags.StringArrayVar(&o.parametersFiles, "parameters-file", []string{}, "Override parameters file")
+	flags.StringArrayVarP(&o.overrides, "set", "s", []string{}, "Override parameter value")
 }
 
 type credentialOptions struct {
@@ -94,8 +94,8 @@ type credentialOptions struct {
 }
 
 func (o *credentialOptions) addFlags(flags *pflag.FlagSet) {
-	flags.StringVar(&o.targetContext, "target-context", "", "Context on which the application is executed")
-	flags.StringArrayVarP(&o.credentialsets, "credential-set", "c", []string{}, "Use a credentialset (either a YAML file, or a credential set present in the credential store)")
+	flags.StringVar(&o.targetContext, "target-context", "", "Context on which the application is installed (default: <current-context>)")
+	flags.StringArrayVar(&o.credentialsets, "credential-set", []string{}, "Use a YAML file containing a credential set or a credential set present in the credential store")
 	flags.BoolVar(&o.sendRegistryAuth, "with-registry-auth", false, "Sends registry auth")
 }
 
diff --git a/internal/commands/split.go b/internal/commands/split.go
@@ -10,9 +10,10 @@ var splitOutputDir string
 
 func splitCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "split [<app-name>] [-o output]",
-		Short: "Split a single-file application into multiple files",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "split [APP_NAME] [--output OUTPUT_DIRECTORY]",
+		Short:   "Split a single-file Docker Application definition into the directory format",
+		Example: `$ docker app split myapp.dockerapp --output myapp-directory.dockerapp`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			extractedApp, err := packager.Extract(firstOrEmpty(args))
 			if err != nil {
@@ -32,6 +33,6 @@ func splitCmd() *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().StringVarP(&splitOutputDir, "output", "o", "", "Output application directory (default: in-place)")
+	cmd.Flags().StringVarP(&splitOutputDir, "output", "o", "", "Output directory (default: in-place)")
 	return cmd
 }
diff --git a/internal/commands/status.go b/internal/commands/status.go
@@ -15,9 +15,11 @@ func statusCmd(dockerCli command.Cli) *cobra.Command {
 	var opts credentialOptions
 
 	cmd := &cobra.Command{
-		Use:   "status <installation-name>",
-		Short: "Get the installation status. If the installation is a docker application, the status shows the stack services.",
-		Args:  cli.ExactArgs(1),
+		Use:     "status INSTALLATION_NAME [--target-context TARGET_CONTEXT] [OPTIONS]",
+		Short:   "Get the installation status of an application",
+		Long:    "Get the installation status of an application. If the installation is a Docker Application, the status shows the stack services.",
+		Example: "$ docker app status myinstallation --target-context=mycontext",
+		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runStatus(dockerCli, args[0], opts)
 		},
diff --git a/internal/commands/uninstall.go b/internal/commands/uninstall.go
diff --git a/internal/commands/upgrade.go b/internal/commands/upgrade.go
diff --git a/internal/commands/validate.go b/internal/commands/validate.go

Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@ func getCnabAction() (cnabAction, string, error) {`
`38`	`38`	`func main() {`
`39`	`39`	`action, actionName, err := getCnabAction()`
`40`	`40`	`if err != nil {`
`41`		`- fmt.Fprintf(os.Stderr, "Error while parsing cnab operation: %s", err)`
	`41`	`+ fmt.Fprintf(os.Stderr, "Error while parsing CNAB operation: %s", err)`
`42`	`42`	`os.Exit(1)`
`43`	`43`	`}`
`44`	`44`	`instanceName := os.Getenv("CNAB_INSTALLATION_NAME")`
Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ func testRenderApp(appPath string, env ...string) func(*testing.T) {`
`60`	`60`	`data, err := ioutil.ReadFile(filepath.Join(appPath, "env.yml"))`
`61`	`61`	`assert.NilError(t, err)`
`62`	`62`	`assert.NilError(t, yaml.Unmarshal(data, &envParameters))`
`63`		`- args := dockerCli.Command("app", "render", filepath.Join(appPath, "my.dockerapp"), "--parameters-files", filepath.Join(appPath, "parameters-0.yml"))`
	`63`	`+ args := dockerCli.Command("app", "render", filepath.Join(appPath, "my.dockerapp"), "--parameters-file", filepath.Join(appPath, "parameters-0.yml"))`
`64`	`64`	`for k, v := range envParameters {`
`65`	`65`	`args = append(args, "--set", fmt.Sprintf("%s=%s", k, v))`
`66`	`66`	`}`