[b9bd12a] Fix object naming in command help and update examples, e2E tests and file linting. Remove bracket changes in command usage message. Take into account feedback from Silvin, Chris and Nicolas.

carolinebriaud · carolinebriaud · commit b07e744df9a4 · 2019-10-24T18:49:28.000+02:00
Signed-off-by: Caroline Briaud &lt;caroline.briaud@docker.com&gt;
diff --git a/e2e/commands_test.go b/e2e/commands_test.go
@@ -190,7 +190,7 @@ func TestRunOnlyOne(t *testing.T) {
 	cmd.Command = dockerCli.Command("app", "run", "--cnab-bundle-json", "bundle.json", "myapp")
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
 		ExitCode: 1,
-		Err:      `"docker app run" cannot run a bundle and an app image`,
+		Err:      `"docker app run" cannot run a bundle and an App image`,
 	})
 }
 
@@ -238,7 +238,7 @@ func testDockerAppLifecycle(t *testing.T, useBindMount bool) {
 	cmd.Command = dockerCli.Command("app", "update", appName)
 	icmd.RunCmd(cmd).Assert(t, icmd.Expected{
 		ExitCode: 1,
-		Err:      fmt.Sprintf("Installation %q has failed and cannot be updated, reinstall it using 'docker app install'", appName),
+		Err:      fmt.Sprintf("Installation %q has failed and cannot be updated, reinstall it using 'docker app run'", appName),
 	})
 
 	// Install a Docker Application Package with an existing failed installation is fine
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 (Docker Inc.,",
+		Out: "app*        Docker App (Docker Inc.,",
 	})
 
 	// docker app --help prints docker-app help
@@ -27,7 +27,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 \(Docker Inc\., .*\)`)
+	re := regexp.MustCompile(`app: Docker App \(Docker Inc\., .*\)`)
 	output := icmd.RunCmd(cmd).Assert(t, icmd.Success).Combined()
 	assert.Assert(t, re.MatchString(output))
 }
diff --git a/e2e/testdata/plugin-usage.golden b/e2e/testdata/plugin-usage.golden
@@ -1,23 +1,23 @@
 
 Usage:	docker app [OPTIONS] COMMAND
 
-A tool to build and manage Docker Applications.
+A tool to build, share and run a Docker App
 
 Options:
       --version   Print version information
 
 Management Commands:
-  image       Manage application images
+  image       Manage App images
 
 Commands:
-  build       Build service images for the application
-  init        Initialize Docker Application definition
-  ls          List the installations and their last known installation result
-  pull        Pull an application package from a registry
-  push        Push an application package to a registry
-  rm          Remove an application
-  run         Run an application
-  update      Update a running application
-  validate    Checks the rendered application is syntactically correct
+  build       Build an App image from an App definition (.dockerapp)
+  init        Initialize an App definition
+  ls          List running Apps
+  pull        Pull an App image from a registry
+  push        Push an App image to a registry
+  rm          Remove a running App
+  run         Run an App from an App image
+  update      Update a running App
+  validate    Check that an App definition (.dockerapp) is syntactically correct
 
 Run 'docker app COMMAND --help' for more information on a command.
diff --git a/internal/commands/build/build.go b/internal/commands/build/build.go
@@ -45,24 +45,25 @@ type buildOptions struct {
 func Cmd(dockerCli command.Cli) *cobra.Command {
 	var opts buildOptions
 	cmd := &cobra.Command{
-		Use:     "build [OPTIONS] [CONTEXT_PATH]",
-		Short:   "Build service images for the application",
-		Example: `$ docker app build --tag my/app:1.0.0 .`,
-		Args:    cli.ExactArgs(1),
+		Use:   "build [OPTIONS] [BUILD_PATH]",
+		Short: "Build an App image from an App definition (.dockerapp)",
+		Example: `$ docker app build .
+$ docker app build . -f myapp.dockerapp -t myrepo/myapp:1.0.0`,
+		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runBuild(dockerCli, args[0], opts)
 		},
 	}
 
 	flags := cmd.Flags()
-	flags.BoolVar(&opts.noCache, "no-cache", false, "Do not use cache when building the image")
+	flags.BoolVar(&opts.noCache, "no-cache", false, "Do not use cache when building the App image")
 	flags.StringVar(&opts.progress, "progress", "auto", "Set type of progress output (auto, plain, tty). Use plain to show container output")
-	flags.StringVarP(&opts.tag, "tag", "t", "", "Application image and optionally a tag in the 'image:tag' format")
-	flags.StringVarP(&opts.folder, "folder", "f", "", "Docker app folder containing application definition")
-	flags.BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the image")
+	flags.StringVarP(&opts.tag, "tag", "t", "", "App image tag, optionally in the 'repo:tag' format")
+	flags.StringVarP(&opts.folder, "folder", "f", "", "App definition as a .dockerapp directory")
+	flags.BoolVar(&opts.pull, "pull", false, "Always attempt to pull a newer version of the App image")
 	flags.StringArrayVar(&opts.args, "build-arg", []string{}, "Set build-time variables")
-	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress the build output and print app image ID on success")
-	flags.StringVar(&opts.imageIDFile, "iidfile", "", "Write the app image ID to the file")
+	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress the build output and print App image ID on success")
+	flags.StringVar(&opts.imageIDFile, "iidfile", "", "Write the App image ID to the file")
 
 	return cmd
 }
@@ -190,7 +191,7 @@ func getAppFolder(opt buildOptions, contextPath string) (string, error) {
 		for _, f := range files {
 			if strings.HasSuffix(f.Name(), ".dockerapp") {
 				if application != "" {
-					return "", fmt.Errorf("%s contains multiple *.dockerapp folders, use -f option to select the one to build", contextPath)
+					return "", fmt.Errorf("%s contains multiple .dockerapp directories, use -f option to select the one to build", contextPath)
 				}
 				application = filepath.Join(contextPath, f.Name())
 				if !f.IsDir() {
diff --git a/internal/commands/image/command.go b/internal/commands/image/command.go
@@ -8,7 +8,7 @@ import (
 // Cmd is the image top level command
 func Cmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Short: "Manage application images",
+		Short: "Manage App images",
 		Use:   "image",
 	}
 
diff --git a/internal/commands/image/inspect.go b/internal/commands/image/inspect.go
@@ -30,16 +30,18 @@ func muteDockerCli(dockerCli command.Cli) func() {
 func inspectCmd(dockerCli command.Cli) *cobra.Command {
 	var opts inspectOptions
 	cmd := &cobra.Command{
-		Use:   "inspect [APP_NAME] [OPTIONS]",
-		Short: "Shows metadata, parameters and a summary of the Compose file for a given application",
-		Example: `$ docker app inspect my-installed-app
-$docker app inspect my-app:1.0.0`,
+		Use:   "inspect [OPTIONS] APP_IMAGE",
+		Short: "Display detailed information about an App image",
+		Example: `$ docker app image inspect myapp
+$ docker app image inspect myapp:1.0.0
+$ docker app image inspect myrepo/myapp:1.0.0
+$ docker app image inspect 34be4a0c5f50`,
 		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runInspect(dockerCli, args[0], opts)
 		},
 	}
-	cmd.Flags().BoolVar(&opts.pretty, "pretty", false, "Pretty print the output")
+	cmd.Flags().BoolVar(&opts.pretty, "pretty", false, "Print the information in a human friendly format")
 
 	return cmd
 }
diff --git a/internal/commands/image/list.go b/internal/commands/image/list.go
@@ -23,7 +23,7 @@ type imageListOption struct {
 func listCmd(dockerCli command.Cli) *cobra.Command {
 	options := imageListOption{}
 	cmd := &cobra.Command{
-		Short:   "List application images",
+		Short:   "List App images",
 		Use:     "ls",
 		Aliases: []string{"list"},
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/image/rm.go b/internal/commands/image/rm.go
@@ -14,13 +14,14 @@ import (
 
 func rmCmd() *cobra.Command {
 	return &cobra.Command{
-		Short:   "Remove an application image",
-		Use:     "rm [APP_IMAGE] [APP_IMAGE...]",
+		Short:   "Remove an App image",
+		Use:     "rm APP_IMAGE [APP_IMAGE...]",
 		Aliases: []string{"remove"},
 		Args:    cli.RequiresMinArgs(1),
 		Example: `$ docker app image rm myapp
 $ docker app image rm myapp:1.0.0
-$ docker app image rm docker.io/library/myapp@sha256:beef...`,
+$ docker app image rm myrepo/myapp@sha256:c0de...
+$ docker app image rm 34be4a0c5f50`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appstore, err := store.NewApplicationStore(config.Dir())
 			if err != nil {
diff --git a/internal/commands/image/tag.go b/internal/commands/image/tag.go
@@ -12,9 +12,12 @@ import (
 
 func tagCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Short: "Create a new tag from an application image",
+		Short: "Create a new tag from an App image",
 		Use:   "tag SOURCE_APP_IMAGE[:TAG] TARGET_APP_IMAGE[:TAG]",
-		Args:  cli.ExactArgs(2),
+		Example: `$ docker app image tag myapp myrepo/myapp:mytag
+$ docker app image tag myapp:tag myrepo/mynewapp:mytag
+$ docker app image tag 34be4a0c5f50 myrepo/mynewapp:mytag`,
+		Args: cli.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			appstore, err := store.NewApplicationStore(config.Dir())
 			if err != nil {
diff --git a/internal/commands/init.go b/internal/commands/init.go
@@ -15,11 +15,11 @@ var (
 
 func initCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "init APP_NAME [--compose-file COMPOSE_FILE] [OPTIONS]",
-		Short:   "Initialize Docker Application definition",
-		Long:    `Start building a Docker Application package.`,
-		Example: `$ docker app init myapp`,
-		Args:    cli.ExactArgs(1),
+		Use:   "init [OPTIONS] APP_DEFINITION",
+		Short: "Initialize an App definition",
+		Example: `$ docker app init myapp
+$ docker app init myapp --compose-file docker-compose.yml`,
+		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			created, err := packager.Init(args[0], initComposeFile)
 			if err != nil {
@@ -29,6 +29,6 @@ func initCmd(dockerCli command.Cli) *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use as application base (optional)")
+	cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use to bootstrap a Docker App definition")
 	return cmd
 }
diff --git a/internal/commands/list.go b/internal/commands/list.go
@@ -44,14 +44,14 @@ func listCmd(dockerCli command.Cli) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "ls [OPTIONS]",
-		Short:   "List the installations and their last known installation result",
+		Short:   "List running Apps",
 		Aliases: []string{"list"},
 		Args:    cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runList(dockerCli, opts)
 		},
 	}
-	cmd.Flags().StringVar(&opts.targetContext, "target-context", "", "List installations on this context")
+	cmd.Flags().StringVar(&opts.targetContext, "target-context", "", "List running Apps on this context")
 
 	return cmd
 }
diff --git a/internal/commands/pull.go b/internal/commands/pull.go
@@ -16,9 +16,9 @@ import (
 
 func pullCmd(dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "pull NAME:TAG [OPTIONS]",
-		Short:   "Pull an application package from a registry",
-		Example: `$ docker app pull docker/app-example:0.1.0`,
+		Use:     "pull APP_IMAGE",
+		Short:   "Pull an App image from a registry",
+		Example: `$ docker app pull myrepo/myapp:0.1.0`,
 		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runPull(dockerCli, args[0])
diff --git a/internal/commands/push.go b/internal/commands/push.go
@@ -53,8 +53,8 @@ type pushOptions struct {
 func pushCmd(dockerCli command.Cli) *cobra.Command {
 	var opts pushOptions
 	cmd := &cobra.Command{
-		Use:     "push [APP_NAME] --tag TARGET_REFERENCE [OPTIONS]",
-		Short:   "Push an application package to a registry",
+		Use:     "push [OPTIONS] APP_IMAGE",
+		Short:   "Push an App image to a registry",
 		Example: `$ docker app push myapp --tag myrepo/myapp:mytag`,
 		Args:    cli.RequiresMaxArgs(1),
 		PreRunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/remove.go b/internal/commands/remove.go
@@ -21,17 +21,17 @@ func removeCmd(dockerCli command.Cli) *cobra.Command {
 	var opts removeOptions
 
 	cmd := &cobra.Command{
-		Use:     "rm INSTALLATION_NAME [--target-context TARGET_CONTEXT] [OPTIONS]",
-		Short:   "Remove an application",
+		Use:     "rm [OPTIONS] RUNNING_APP",
+		Short:   "Remove a running App",
 		Aliases: []string{"remove"},
-		Example: `$ docker app rm myinstallation --target-context=mycontext`,
+		Example: `$ docker app rm myrunningapp`,
 		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runRemove(dockerCli, args[0], opts)
 		},
 	}
 	opts.addFlags(cmd.Flags())
-	cmd.Flags().BoolVar(&opts.force, "force", false, "Force removal of installation")
+	cmd.Flags().BoolVar(&opts.force, "force", false, "Force the removal of a running App")
 
 	return cmd
 }
diff --git a/internal/commands/render.go b/internal/commands/render.go
@@ -25,9 +25,9 @@ type renderOptions struct {
 func renderCmd(dockerCli command.Cli) *cobra.Command {
 	var opts renderOptions
 	cmd := &cobra.Command{
-		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`,
+		Use:     "render [OPTIONS] APP_IMAGE",
+		Short:   "Render the Compose file for an App image",
+		Example: `$ docker app render myrepo/myapp:1.0.0 --set key=value --parameters-file myparam.yml`,
 		Args:    cli.RequiresMaxArgs(1),
 		Hidden:  true,
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/root.go b/internal/commands/root.go
@@ -24,8 +24,8 @@ var (
 // NewRootCmd returns the base root command.
 func NewRootCmd(use string, dockerCli command.Cli) *cobra.Command {
 	cmd := &cobra.Command{
-		Short:       "Docker Application",
-		Long:        `A tool to build and manage Docker Applications.`,
+		Short:       "Docker App",
+		Long:        `A tool to build, share and run a Docker App`,
 		Use:         use,
 		Annotations: map[string]string{"experimentalCLI": "true"},
 		RunE: func(cmd *cobra.Command, args []string) error {
diff --git a/internal/commands/run.go b/internal/commands/run.go
@@ -27,23 +27,24 @@ type runOptions struct {
 	cnabBundle    string
 }
 
-const longDescription = `Run an application based on a docker app image.`
+const longDescription = `Run an App from an App image.`
 
-const example = `$ docker app run --name myinstallation --target-context=mycontext myrepo/myapp:mytag`
+const example = `$ docker app run --name myrunningapp myrepo/myapp:mytag
+$ docker app run 34be4a0c5f50 --name myrunningapp`
 
 func runCmd(dockerCli command.Cli) *cobra.Command {
 	var opts runOptions
 
 	cmd := &cobra.Command{
-		Use:     "run [OPTIONS] [APP_IMAGE]",
+		Use:     "run [OPTIONS] APP_IMAGE",
 		Aliases: []string{"deploy"},
-		Short:   "Run an application",
+		Short:   "Run an App from an App image",
 		Long:    longDescription,
 		Example: example,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if opts.cnabBundle != "" && len(args) != 0 {
 				return errors.Errorf(
-					"%q cannot run a bundle and an app image",
+					"%q cannot run a bundle and an App image",
 					cmd.CommandPath(),
 				)
 			}
@@ -58,10 +59,10 @@ func runCmd(dockerCli command.Cli) *cobra.Command {
 	}
 	opts.parametersOptions.addFlags(cmd.Flags())
 	opts.credentialOptions.addFlags(cmd.Flags())
-	cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to install on (swarm, kubernetes)")
-	cmd.Flags().StringVar(&opts.kubeNamespace, "namespace", "default", "Kubernetes namespace to install into")
-	cmd.Flags().StringVar(&opts.stackName, "name", "", "Assign a name to the installation")
-	cmd.Flags().StringVar(&opts.cnabBundle, "cnab-bundle-json", "", "Run a CNAB bundle instead of a Docker App")
+	cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to run on (swarm, kubernetes)")
+	cmd.Flags().StringVar(&opts.kubeNamespace, "namespace", "default", "Kubernetes namespace in which to run the App")
+	cmd.Flags().StringVar(&opts.stackName, "name", "", "Name of the running App")
+	cmd.Flags().StringVar(&opts.cnabBundle, "cnab-bundle-json", "", "Run a CNAB bundle instead of a Docker App image")
 
 	return cmd
 }
diff --git a/internal/commands/update.go b/internal/commands/update.go
@@ -21,16 +21,16 @@ func updateCmd(dockerCli command.Cli) *cobra.Command {
 	var opts updateOptions
 	cmd := &cobra.Command{
 		Use:     "update [OPTIONS] RUNNING_APP",
-		Short:   "Update a running application",
-		Example: `$ docker app update myrunningapp --target-context=mycontext --set key=value`,
+		Short:   "Update a running App",
+		Example: `$ docker app update myrunningapp --set key=value`,
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runUpdate(dockerCli, args[0], opts)
 		},
 	}
 	opts.parametersOptions.addFlags(cmd.Flags())
 	opts.credentialOptions.addFlags(cmd.Flags())
-	cmd.Flags().StringVar(&opts.bundleOrDockerApp, "image", "", "Override the installation with another Application Package")
+	cmd.Flags().StringVar(&opts.bundleOrDockerApp, "image", "", "Override the running App with another App image")
 
 	return cmd
 }
@@ -50,7 +50,7 @@ func runUpdate(dockerCli command.Cli, installationName string, opts updateOption
 	}
 
 	if isInstallationFailed(installation) {
-		return fmt.Errorf("Installation %q has failed and cannot be updated, reinstall it using 'docker app install'", installationName)
+		return fmt.Errorf("Installation %q has failed and cannot be updated, reinstall it using 'docker app run'", installationName)
 	}
 
 	if opts.bundleOrDockerApp != "" {
diff --git a/internal/commands/validate.go b/internal/commands/validate.go
@@ -19,9 +19,10 @@ type validateOptions struct {
 func validateCmd() *cobra.Command {
 	var opts validateOptions
 	cmd := &cobra.Command{
-		Use:   "validate [APP_NAME] [--set KEY=VALUE ...] [--parameters-file PARAMETERS_FILE]",
-		Short: "Checks the rendered application is syntactically correct",
-		Args:  cli.RequiresMaxArgs(1),
+		Use:     "validate [OPTIONS] APP_DEFINITION",
+		Short:   "Check that an App definition (.dockerapp) is syntactically correct",
+		Example: `$ docker app validate myapp.dockerapp --set key=value --parameters-file myparam.yml`,
+		Args:    cli.RequiresMaxArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			app, err := packager.Extract(firstOrEmpty(args),
 				types.WithParametersFiles(opts.parametersFiles...),

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ import (`
`8`	`8`	`// Cmd is the image top level command`
`9`	`9`	`func Cmd(dockerCli command.Cli) *cobra.Command {`
`10`	`10`	`cmd := &cobra.Command{`
`11`		`- Short: "Manage application images",`
	`11`	`+ Short: "Manage App images",`
`12`	`12`	`Use: "image",`
`13`	`13`	`}`
`14`	`14`