Make kubectl help strings consistent

docs/devel/kubectl-conventions.md

@@ -125,6 +125,9 @@ flags and separate help that is tailored for the particular usage.
 * Flag names and single-character aliases should have the same meaning across
 all commands
 
+* Flag descriptions should start with an uppercase letter and not have a
+period at the end of a sentence
+
 * Command-line flags corresponding to API fields should accept API enums
 exactly (e.g., `--restart=Always`)
 
@@ -233,9 +236,16 @@ resources in other commands
 an exhaustive specification
 
   * Short should contain a one-line explanation of what the command does
+    * Short descriptions should start with an uppercase case letter and not
+    have a period at the end of a sentence
+    * Short descriptions should (if possible) start with a first person
+    (singular present tense) verb
 
   * Long may contain multiple lines, including additional information about
 input, output, commonly used flags, etc.
+    * Long descriptions should use proper grammar, start with an uppercase
+    letter and have a period at the end of a sentence
+
 
   * Example should contain examples
     * Start commands with `$`

pkg/client/unversioned/clientcmd/overrides.go

@@ -124,12 +124,12 @@ const (
 // RecommendedAuthOverrideFlags is a convenience method to return recommended flag names prefixed with a string of your choosing
 func RecommendedAuthOverrideFlags(prefix string) AuthOverrideFlags {
 	return AuthOverrideFlags{
-		ClientCertificate: FlagInfo{prefix + FlagCertFile, "", "", "Path to a client certificate file for TLS."},
-		ClientKey:         FlagInfo{prefix + FlagKeyFile, "", "", "Path to a client key file for TLS."},
-		Token:             FlagInfo{prefix + FlagBearerToken, "", "", "Bearer token for authentication to the API server."},
-		Impersonate:       FlagInfo{prefix + FlagImpersonate, "", "", "Username to impersonate for the operation."},
-		Username:          FlagInfo{prefix + FlagUsername, "", "", "Username for basic authentication to the API server."},
-		Password:          FlagInfo{prefix + FlagPassword, "", "", "Password for basic authentication to the API server."},
+		ClientCertificate: FlagInfo{prefix + FlagCertFile, "", "", "Path to a client certificate file for TLS"},
+		ClientKey:         FlagInfo{prefix + FlagKeyFile, "", "", "Path to a client key file for TLS"},
+		Token:             FlagInfo{prefix + FlagBearerToken, "", "", "Bearer token for authentication to the API server"},
+		Impersonate:       FlagInfo{prefix + FlagImpersonate, "", "", "Username to impersonate for the operation"},
+		Username:          FlagInfo{prefix + FlagUsername, "", "", "Username for basic authentication to the API server"},
+		Password:          FlagInfo{prefix + FlagPassword, "", "", "Password for basic authentication to the API server"},
 	}
 }
 
@@ -138,8 +138,8 @@ func RecommendedClusterOverrideFlags(prefix string) ClusterOverrideFlags {
 	return ClusterOverrideFlags{
 		APIServer:             FlagInfo{prefix + FlagAPIServer, "", "", "The address and port of the Kubernetes API server"},
 		APIVersion:            FlagInfo{prefix + FlagAPIVersion, "", "", "DEPRECATED: The API version to use when talking to the server"},
-		CertificateAuthority:  FlagInfo{prefix + FlagCAFile, "", "", "Path to a cert. file for the certificate authority."},
-		InsecureSkipTLSVerify: FlagInfo{prefix + FlagInsecure, "", "false", "If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure."},
+		CertificateAuthority:  FlagInfo{prefix + FlagCAFile, "", "", "Path to a cert. file for the certificate authority"},
+		InsecureSkipTLSVerify: FlagInfo{prefix + FlagInsecure, "", "false", "If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure"},
 	}
 }
 
@@ -158,7 +158,7 @@ func RecommendedContextOverrideFlags(prefix string) ContextOverrideFlags {
 	return ContextOverrideFlags{
 		ClusterName:  FlagInfo{prefix + FlagClusterName, "", "", "The name of the kubeconfig cluster to use"},
 		AuthInfoName: FlagInfo{prefix + FlagAuthInfoName, "", "", "The name of the kubeconfig user to use"},
-		Namespace:    FlagInfo{prefix + FlagNamespace, "", "", "If present, the namespace scope for this CLI request."},
+		Namespace:    FlagInfo{prefix + FlagNamespace, "", "", "If present, the namespace scope for this CLI request"},
 	}
 }
 

pkg/kubectl/cmd/apiversions.go

@@ -33,7 +33,7 @@ func NewCmdApiVersions(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 		Use: "api-versions",
 		// apiversions is deprecated.
 		Aliases: []string{"apiversions"},
-		Short:   "Print the supported API versions on the server, in the form of \"group/version\".",
+		Short:   "Print the supported API versions on the server, in the form of \"group/version\"",
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunApiVersions(f, out)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/attach.go

@@ -59,7 +59,7 @@ func NewCmdAttach(f *cmdutil.Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer)
 	}
 	cmd := &cobra.Command{
 		Use:     "attach POD -c CONTAINER",
-		Short:   "Attach to a running container.",
+		Short:   "Attach to a running container",
 		Long:    "Attach to a process that is already running inside an existing container.",
 		Example: attach_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/clusterinfo_dump.go

@@ -34,7 +34,7 @@ import (
 func NewCmdClusterInfoDump(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "dump",
-		Short:   "Dump lots of relevant info for debugging and diagnosis.",
+		Short:   "Dump lots of relevant info for debugging and diagnosis",
 		Long:    dumpLong,
 		Example: dumpExample,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/config/config.go

@@ -33,8 +33,8 @@ func NewCmdConfig(pathOptions *clientcmd.PathOptions, out io.Writer) *cobra.Comm
 
 	cmd := &cobra.Command{
 		Use:   "config SUBCOMMAND",
-		Short: "config modifies kubeconfig files",
-		Long: `config modifies kubeconfig files using subcommands like "kubectl config set current-context my-context"
+		Short: "Modify kubeconfig files",
+		Long: `Modify kubeconfig files using subcommands like "kubectl config set current-context my-context"
 
 The loading order follows these rules:
 1. If the --` + pathOptions.ExplicitFileFlag + ` flag is set, then only that file is loaded.  The flag may only be set once and no merging takes place.

pkg/kubectl/cmd/config/view.go

@@ -42,7 +42,7 @@ type ViewOptions struct {
 
 var (
 	view_long = dedent.Dedent(`
-		Displays merged kubeconfig settings or a specified kubeconfig file.
+		Display merged kubeconfig settings or a specified kubeconfig file.
 
 		You can use --output jsonpath={...} to extract specific values using a jsonpath expression.`)
 	view_example = dedent.Dedent(`
@@ -60,7 +60,7 @@ func NewCmdConfigView(out io.Writer, ConfigAccess clientcmd.ConfigAccess) *cobra
 
 	cmd := &cobra.Command{
 		Use:     "view",
-		Short:   "Displays merged kubeconfig settings or a specified kubeconfig file.",
+		Short:   "Display merged kubeconfig settings or a specified kubeconfig file",
 		Long:    view_long,
 		Example: view_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/create_configmap.go

@@ -48,15 +48,15 @@ var (
 		  # Create a new configmap named my-config with specified keys instead of names on disk
 		  kubectl create configmap my-config --from-file=key1=/path/to/bar/file1.txt --from-file=key2=/path/to/bar/file2.txt
 
-		  # Create a new configMap named my-config with key1=config1 and key2=config2
+		  # Create a new configmap named my-config with key1=config1 and key2=config2
 		  kubectl create configmap my-config --from-literal=key1=config1 --from-literal=key2=config2`)
 )
 
 // ConfigMap is a command to ease creating ConfigMaps.
 func NewCmdCreateConfigMap(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "configmap NAME [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run]",
-		Short:   "Create a configMap from a local file, directory or literal value.",
+		Short:   "Create a configmap from a local file, directory or literal value",
 		Long:    configMapLong,
 		Example: configMapExample,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/create_namespace.go

@@ -41,7 +41,7 @@ func NewCmdCreateNamespace(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command
 	cmd := &cobra.Command{
 		Use:     "namespace NAME [--dry-run]",
 		Aliases: []string{"ns"},
-		Short:   "Create a namespace with the specified name.",
+		Short:   "Create a namespace with the specified name",
 		Long:    namespaceLong,
 		Example: namespaceExample,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/create_secret.go

@@ -31,7 +31,7 @@ import (
 func NewCmdCreateSecret(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "secret",
-		Short: "Create a secret using specified subcommand.",
+		Short: "Create a secret using specified subcommand",
 		Long:  "Create a secret using specified subcommand.",
 		Run: func(cmd *cobra.Command, args []string) {
 			cmd.Help()
@@ -73,7 +73,7 @@ var (
 func NewCmdCreateSecretGeneric(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "generic NAME [--type=string] [--from-file=[key=]source] [--from-literal=key1=value1] [--dry-run]",
-		Short:   "Create a secret from a local file, directory or literal value.",
+		Short:   "Create a secret from a local file, directory or literal value",
 		Long:    secretLong,
 		Example: secretExample,
 		Run: func(cmd *cobra.Command, args []string) {
@@ -141,7 +141,7 @@ var (
 func NewCmdCreateSecretDockerRegistry(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "docker-registry NAME --docker-username=user --docker-password=password --docker-email=email [--docker-server=string] [--from-literal=key1=value1] [--dry-run]",
-		Short:   "Create a secret for use with a Docker registry.",
+		Short:   "Create a secret for use with a Docker registry",
 		Long:    secretForDockerRegistryLong,
 		Example: secretForDockerRegistryExample,
 		Run: func(cmd *cobra.Command, args []string) {
@@ -212,7 +212,7 @@ var (
 func NewCmdCreateSecretTLS(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "tls NAME --cert=path/to/cert/file --key=path/to/key/file [--dry-run]",
-		Short:   "Create a TLS secret.",
+		Short:   "Create a TLS secret",
 		Long:    secretForTLSLong,
 		Example: secretForTLSExample,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/create_serviceaccount.go

@@ -41,7 +41,7 @@ func NewCmdCreateServiceAccount(f *cmdutil.Factory, cmdOut io.Writer) *cobra.Com
 	cmd := &cobra.Command{
 		Use:     "serviceaccount NAME [--dry-run]",
 		Aliases: []string{"sa"},
-		Short:   "Create a service account with the specified name.",
+		Short:   "Create a service account with the specified name",
 		Long:    serviceAccountLong,
 		Example: serviceAccountExample,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/delete.go

@@ -87,7 +87,7 @@ func NewCmdDelete(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "delete ([-f FILENAME] | TYPE [(NAME | -l label | --all)])",
-		Short:   "Delete resources by filenames, stdin, resources and names, or by resources and label selector.",
+		Short:   "Delete resources by filenames, stdin, resources and names, or by resources and label selector",
 		Long:    delete_long,
 		Example: delete_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/exec.go

@@ -59,7 +59,7 @@ func NewCmdExec(f *cmdutil.Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer) *
 	}
 	cmd := &cobra.Command{
 		Use:     "exec POD [-c CONTAINER] -- COMMAND [args...]",
-		Short:   "Execute a command in a container.",
+		Short:   "Execute a command in a container",
 		Long:    "Execute a command in a container.",
 		Example: exec_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/explain.go

@@ -46,7 +46,7 @@ var (
 func NewCmdExplain(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "explain RESOURCE",
-		Short:   "Documentation of resources.",
+		Short:   "Documentation of resources",
 		Long:    explainLong,
 		Example: explainExamples,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/logs.go

@@ -74,7 +74,7 @@ func NewCmdLogs(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 	o := &LogsOptions{}
 	cmd := &cobra.Command{
 		Use:     "logs [-f] [-p] POD [-c CONTAINER]",
-		Short:   "Print the logs for a container in a pod.",
+		Short:   "Print the logs for a container in a pod",
 		Long:    "Print the logs for a container in a pod. If the pod has only one container, the container name is optional.",
 		Example: logs_example,
 		PreRun: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/patch.go

@@ -83,7 +83,7 @@ func NewCmdPatch(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "patch (-f FILENAME | TYPE NAME) -p PATCH",
-		Short:   "Update field(s) of a resource using strategic merge patch.",
+		Short:   "Update field(s) of a resource using strategic merge patch",
 		Long:    patch_long,
 		Example: patch_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/portforward.go

@@ -50,7 +50,7 @@ var (
 func NewCmdPortForward(f *cmdutil.Factory, cmdOut, cmdErr io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]",
-		Short:   "Forward one or more local ports to a pod.",
+		Short:   "Forward one or more local ports to a pod",
 		Long:    "Forward one or more local ports to a pod.",
 		Example: portforward_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/replace.go

@@ -69,7 +69,7 @@ func NewCmdReplace(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 		Use: "replace -f FILENAME",
 		// update is deprecated.
 		Aliases: []string{"update"},
-		Short:   "Replace a resource by filename or stdin.",
+		Short:   "Replace a resource by filename or stdin",
 		Long:    replace_long,
 		Example: replace_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/rollingupdate.go

@@ -82,7 +82,7 @@ func NewCmdRollingUpdate(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 		Use: "rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE | -f NEW_CONTROLLER_SPEC)",
 		// rollingupdate is deprecated.
 		Aliases: []string{"rollingupdate"},
-		Short:   "Perform a rolling update of the given ReplicationController.",
+		Short:   "Perform a rolling update of the given ReplicationController",
 		Long:    rollingUpdate_long,
 		Example: rollingUpdate_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/rollout/rollout.go

@@ -26,7 +26,7 @@ import (
 
 var (
 	rollout_long = dedent.Dedent(`
-		Manages a deployment using subcommands like "kubectl rollout undo deployment/abc"`)
+		Manage a deployment using subcommands like "kubectl rollout undo deployment/abc"`)
 	rollout_example = dedent.Dedent(`
 		# Rollback to the previous deployment
 		kubectl rollout undo deployment/abc`)
@@ -40,7 +40,7 @@ func NewCmdRollout(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "rollout SUBCOMMAND",
-		Short:   "rollout manages a deployment",
+		Short:   "Manage a deployment rollout",
 		Long:    rollout_long,
 		Example: rollout_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/rollout/rollout_history.go

@@ -51,7 +51,7 @@ func NewCmdRolloutHistory(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "history (TYPE NAME | TYPE/NAME) [flags]",
-		Short:   "view rollout history",
+		Short:   "View rollout history",
 		Long:    history_long,
 		Example: history_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/rollout/rollout_undo.go

@@ -60,7 +60,7 @@ func NewCmdRolloutUndo(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "undo (TYPE NAME | TYPE/NAME) [flags]",
-		Short:   "undoes a previous rollout",
+		Short:   "Undo a previous rollout",
 		Long:    undo_long,
 		Example: undo_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/run.go

@@ -77,7 +77,7 @@ func NewCmdRun(f *cmdutil.Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer) *c
 		Use: "run NAME --image=image [--env=\"key=value\"] [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json] [--command] -- [COMMAND] [args...]",
 		// run-container is deprecated
 		Aliases: []string{"run-container"},
-		Short:   "Run a particular image on the cluster.",
+		Short:   "Run a particular image on the cluster",
 		Long:    run_long,
 		Example: run_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/scale.go

@@ -70,7 +70,7 @@ func NewCmdScale(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 		Use: "scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT (-f FILENAME | TYPE NAME)",
 		// resize is deprecated
 		Aliases: []string{"resize"},
-		Short:   "Set a new size for a Deployment, ReplicaSet, Replication Controller, or Job.",
+		Short:   "Set a new size for a Deployment, ReplicaSet, Replication Controller, or Job",
 		Long:    scale_long,
 		Example: scale_example,
 		Run: func(cmd *cobra.Command, args []string) {

pkg/kubectl/cmd/stop.go

@@ -62,7 +62,7 @@ func NewCmdStop(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:        "stop (-f FILENAME | TYPE (NAME | -l label | --all))",
-		Short:      "Deprecated: Gracefully shut down a resource by name or filename.",
+		Short:      "Deprecated: Gracefully shut down a resource by name or filename",
 		Long:       stop_long,
 		Example:    stop_example,
 		Deprecated: fmt.Sprintf("use %q instead.", "delete"),

pkg/kubectl/cmd/version.go

@@ -28,7 +28,7 @@ import (
 func NewCmdVersion(f *cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "version",
-		Short: "Print the client and server version information.",
+		Short: "Print the client and server version information",
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunVersion(f, out, cmd)
 			cmdutil.CheckErr(err)