From e844ceb2b153824740ff1c9ce80a9ca1357cfd27 Mon Sep 17 00:00:00 2001 From: Moritz Sanft <58110325+stdoutput@users.noreply.github.com> Date: Tue, 17 Jan 2023 14:01:56 +0100 Subject: [PATCH] cli: adopt Cobra cli reference style (#997) * adapt to Cobra CLI ref style * linting * change multi-line reference style * lowercase short descriptions * Revert "lowercase short descriptions" This reverts commit 499dc3577a0b16859027e0fba88dc22a4774223b. * use 2 newlines on long description and add dots * mark required flags * Update cli/internal/cmd/iamcreateaws.go Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> * Update cli/internal/cmd/upgradeexecute.go Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> * Update cli/internal/cmd/upgradeexecute.go Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> Co-authored-by: Paul Meyer <49727155+katexochen@users.noreply.github.com> --- cli/internal/cmd/configfetchmeasurements.go | 7 ++++--- cli/internal/cmd/iam.go | 2 +- cli/internal/cmd/iamcreateaws.go | 8 +++++--- cli/internal/cmd/iamcreateazure.go | 8 ++++---- cli/internal/cmd/iamcreategcp.go | 11 +++++++---- cli/internal/cmd/init.go | 7 ++++--- cli/internal/cmd/miniup.go | 6 +++--- cli/internal/cmd/recover.go | 4 ++-- cli/internal/cmd/terminate.go | 7 ++++--- cli/internal/cmd/upgradeexecute.go | 9 ++++++--- dev-docs/conventions.md | 12 +++++++++++- 11 files changed, 51 insertions(+), 30 deletions(-) diff --git a/cli/internal/cmd/configfetchmeasurements.go b/cli/internal/cmd/configfetchmeasurements.go index 9c7f76592..5e2172d9c 100644 --- a/cli/internal/cmd/configfetchmeasurements.go +++ b/cli/internal/cmd/configfetchmeasurements.go @@ -30,9 +30,10 @@ func newConfigFetchMeasurementsCmd() *cobra.Command { cmd := &cobra.Command{ Use: "fetch-measurements", Short: "Fetch measurements for configured cloud provider and image", - Long: "Fetch measurements for configured cloud provider and image. A config needs to be generated first!", - Args: cobra.ExactArgs(0), - RunE: runConfigFetchMeasurements, + Long: "Fetch measurements for configured cloud provider and image.\n\n" + + "A config needs to be generated first.", + Args: cobra.ExactArgs(0), + RunE: runConfigFetchMeasurements, } cmd.Flags().StringP("url", "u", "", "alternative URL to fetch measurements from") cmd.Flags().StringP("signature-url", "s", "", "alternative URL to fetch measurements' signature from") diff --git a/cli/internal/cmd/iam.go b/cli/internal/cmd/iam.go index 6bd5d4cd9..c051546fd 100644 --- a/cli/internal/cmd/iam.go +++ b/cli/internal/cmd/iam.go @@ -32,7 +32,7 @@ func newIAMCreateCmd() *cobra.Command { Args: cobra.ExactArgs(0), } - cmd.PersistentFlags().Bool("generate-config", false, "Automatically generate a config file and fill in the required fields") + cmd.PersistentFlags().Bool("generate-config", false, "automatically generate a configuration file and fill in the required fields") cmd.AddCommand(newIAMCreateAWSCmd()) cmd.AddCommand(newIAMCreateAzureCmd()) diff --git a/cli/internal/cmd/iamcreateaws.go b/cli/internal/cmd/iamcreateaws.go index 8691e7ad3..28261ef79 100644 --- a/cli/internal/cmd/iamcreateaws.go +++ b/cli/internal/cmd/iamcreateaws.go @@ -26,11 +26,13 @@ func newIAMCreateAWSCmd() *cobra.Command { RunE: runIAMCreateAWS, } - cmd.Flags().String("prefix", "", "Name prefix for all resources.") + cmd.Flags().String("prefix", "", "name prefix for all resources (required)") must(cobra.MarkFlagRequired(cmd.Flags(), "prefix")) - cmd.Flags().String("zone", "", "AWS availability zone the resources will be created in (e.g. us-east-2a). Find available zones here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones. Note that we do not support every zone / region. You can find a list of all supported regions in our docs.") + cmd.Flags().String("zone", "", "AWS availability zone the resources will be created in, e.g. us-east-2a (required)\n"+ + "Find available zones here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones. "+ + "Note that we do not support every zone / region. You can find a list of all supported regions in our docs.") must(cobra.MarkFlagRequired(cmd.Flags(), "zone")) - cmd.Flags().Bool("yes", false, "Create the IAM configuration without further confirmation.") + cmd.Flags().Bool("yes", false, "create the IAM configuration without further confirmation") return cmd } diff --git a/cli/internal/cmd/iamcreateazure.go b/cli/internal/cmd/iamcreateazure.go index b56b8680f..2f001a5b2 100644 --- a/cli/internal/cmd/iamcreateazure.go +++ b/cli/internal/cmd/iamcreateazure.go @@ -25,13 +25,13 @@ func newIAMCreateAzureCmd() *cobra.Command { RunE: runIAMCreateAzure, } - cmd.Flags().String("resourceGroup", "", "Name prefix of the two resource groups your cluster / IAM resources will be created in.") + cmd.Flags().String("resourceGroup", "", "name prefix of the two resource groups your cluster / IAM resources will be created in (required)") must(cobra.MarkFlagRequired(cmd.Flags(), "resourceGroup")) - cmd.Flags().String("region", "", "Region the resources will be created in. (e.g. westus)") + cmd.Flags().String("region", "", "region the resources will be created in, e.g. westus (required)") must(cobra.MarkFlagRequired(cmd.Flags(), "region")) - cmd.Flags().String("servicePrincipal", "", "Name of the service principal that will be created.") + cmd.Flags().String("servicePrincipal", "", "name of the service principal that will be created (required)") must(cobra.MarkFlagRequired(cmd.Flags(), "servicePrincipal")) - cmd.Flags().Bool("yes", false, "Create the IAM configuration without further confirmation.") + cmd.Flags().Bool("yes", false, "create the IAM configuration without further confirmation") return cmd } diff --git a/cli/internal/cmd/iamcreategcp.go b/cli/internal/cmd/iamcreategcp.go index 89f41653a..16fa20543 100644 --- a/cli/internal/cmd/iamcreategcp.go +++ b/cli/internal/cmd/iamcreategcp.go @@ -37,13 +37,16 @@ func newIAMCreateGCPCmd() *cobra.Command { RunE: runIAMCreateGCP, } - cmd.Flags().String("zone", "", "GCP zone the cluster will be deployed in. Find a list of available zones here: https://cloud.google.com/compute/docs/regions-zones#available") + cmd.Flags().String("zone", "", "GCP zone the cluster will be deployed in (required)\n"+ + "Find a list of available zones here: https://cloud.google.com/compute/docs/regions-zones#available.") must(cobra.MarkFlagRequired(cmd.Flags(), "zone")) - cmd.Flags().String("serviceAccountID", "", "ID for the service account that will be created. Must match ^[a-z](?:[-a-z0-9]{4,28}[a-z0-9])$") + cmd.Flags().String("serviceAccountID", "", "ID for the service account that will be created (required)\n"+ + "Must match ^[a-z](?:[-a-z0-9]{4,28}[a-z0-9])$.") must(cobra.MarkFlagRequired(cmd.Flags(), "serviceAccountID")) - cmd.Flags().String("projectID", "", "ID of the GCP project the configuration will be created in. Find it on the welcome screen of your project: https://console.cloud.google.com/welcome") + cmd.Flags().String("projectID", "", "ID of the GCP project the configuration will be created in (required)\n"+ + "Find it on the welcome screen of your project: https://console.cloud.google.com/welcome.") must(cobra.MarkFlagRequired(cmd.Flags(), "projectID")) - cmd.Flags().Bool("yes", false, "Create the IAM configuration without further confirmation.") + cmd.Flags().Bool("yes", false, "create the IAM configuration without further confirmation") return cmd } diff --git a/cli/internal/cmd/init.go b/cli/internal/cmd/init.go index b7c78a4be..4d39de07b 100644 --- a/cli/internal/cmd/init.go +++ b/cli/internal/cmd/init.go @@ -44,9 +44,10 @@ func NewInitCmd() *cobra.Command { cmd := &cobra.Command{ Use: "init", Short: "Initialize the Constellation cluster", - Long: "Initialize the Constellation cluster. Start your confidential Kubernetes.", - Args: cobra.ExactArgs(0), - RunE: runInitialize, + Long: "Initialize the Constellation cluster.\n\n" + + "Start your confidential Kubernetes.", + Args: cobra.ExactArgs(0), + RunE: runInitialize, } cmd.Flags().String("master-secret", "", "path to base64-encoded master secret") cmd.Flags().Bool("conformance", false, "enable conformance mode") diff --git a/cli/internal/cmd/miniup.go b/cli/internal/cmd/miniup.go index 444594892..f7cf0d463 100644 --- a/cli/internal/cmd/miniup.go +++ b/cli/internal/cmd/miniup.go @@ -34,14 +34,14 @@ func newMiniUpCmd() *cobra.Command { cmd := &cobra.Command{ Use: "up", Short: "Create and initialize a new MiniConstellation cluster", - Long: "Create and initialize a new MiniConstellation cluster.\n" + - "A mini cluster consists of a single control-plane and worker node, hosted using QEMU/KVM.\n", + Long: "Create and initialize a new MiniConstellation cluster.\n\n" + + "A mini cluster consists of a single control-plane and worker node, hosted using QEMU/KVM.", Args: cobra.ExactArgs(0), RunE: runUp, } // override global flag so we don't have a default value for the config - cmd.Flags().String("config", "", "path to the config file to use for the cluster") + cmd.Flags().String("config", "", "path to the configuration file to use for the cluster") return cmd } diff --git a/cli/internal/cmd/recover.go b/cli/internal/cmd/recover.go index 801c09f87..2d45c4ff5 100644 --- a/cli/internal/cmd/recover.go +++ b/cli/internal/cmd/recover.go @@ -35,8 +35,8 @@ func NewRecoverCmd() *cobra.Command { cmd := &cobra.Command{ Use: "recover", Short: "Recover a completely stopped Constellation cluster", - Long: "Recover a Constellation cluster by sending a recovery key to an instance in the boot stage." + - "\nThis is only required if instances restart without other instances available for bootstrapping.", + Long: "Recover a Constellation cluster by sending a recovery key to an instance in the boot stage.\n\n" + + "This is only required if instances restart without other instances available for bootstrapping.", Args: cobra.ExactArgs(0), RunE: runRecover, } diff --git a/cli/internal/cmd/terminate.go b/cli/internal/cmd/terminate.go index c96f77f52..79103b309 100644 --- a/cli/internal/cmd/terminate.go +++ b/cli/internal/cmd/terminate.go @@ -25,9 +25,10 @@ func NewTerminateCmd() *cobra.Command { cmd := &cobra.Command{ Use: "terminate", Short: "Terminate a Constellation cluster", - Long: "Terminate a Constellation cluster. The cluster can't be started again, and all persistent storage will be lost.", - Args: cobra.NoArgs, - RunE: runTerminate, + Long: "Terminate a Constellation cluster.\n\n" + + "The cluster can't be started again, and all persistent storage will be lost.", + Args: cobra.NoArgs, + RunE: runTerminate, } cmd.Flags().BoolP("yes", "y", false, "terminate the cluster without further confirmation") return cmd diff --git a/cli/internal/cmd/upgradeexecute.go b/cli/internal/cmd/upgradeexecute.go index 9f33da0b6..1fe931d5b 100644 --- a/cli/internal/cmd/upgradeexecute.go +++ b/cli/internal/cmd/upgradeexecute.go @@ -31,9 +31,12 @@ func newUpgradeExecuteCmd() *cobra.Command { RunE: runUpgradeExecute, } - cmd.Flags().Bool("helm", false, "Execute helm upgrade. This feature is still in development an may change without anounncement. Upgrades all helm charts deployed during constellation-init.") - cmd.Flags().BoolP("yes", "y", false, "Run upgrades without further confirmation. WARNING: might delete your resources in case you are using cert-manager in your cluster. Please read the docs.") - cmd.Flags().Duration("timeout", 3*time.Minute, "Change helm upgrade timeout. This feature is still in development an may change without anounncement. Might be useful for slow connections or big clusters.") + cmd.Flags().Bool("helm", false, "execute helm upgrade\n"+ + "This feature is still in development an may change without announcement. Upgrades all helm charts deployed during constellation-init.") + cmd.Flags().BoolP("yes", "y", false, "run upgrades without further confirmation\n"+ + "WARNING: might delete your resources in case you are using cert-manager in your cluster. Please read the docs.") + cmd.Flags().Duration("timeout", 3*time.Minute, "change helm upgrade timeout\n"+ + "This feature is still in development an may change without announcement. Might be useful for slow connections or big clusters.") if err := cmd.Flags().MarkHidden("helm"); err != nil { panic(err) } diff --git a/dev-docs/conventions.md b/dev-docs/conventions.md index e1f2d0773..e17e44576 100644 --- a/dev-docs/conventions.md +++ b/dev-docs/conventions.md @@ -77,7 +77,7 @@ Further we try to adhere to the following guidelines: ``` * Use the `With()` method to add structured context to your log messages. The context tags should be easily searchable to allow for easy log filtering. Try to keep consistent tag naming! - + Example: ```Go @@ -169,6 +169,16 @@ In case the scope of your PR is too wide, use the alternative format. and `` starts with a capital letter. +## CLI reference + +The command reference within the CLI should follow the following conventions: + +- Short description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends without a period. It should be a single sentence. +- Long description: Starts with a capital letter, beginnings of sentences, names and acronyms are capitalized, ends with a period. + - If the long description contains multiple sentences, the first sentence is formatted as a long description, followed by 2 newlines and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period. +- Flag: Starts with a lowercase letter, beginnings of sentences, names and acronyms are capitalized, ends without a period. + - If a flag contains multiple sentences, the first sentence is formatted as a normal flag, followed by a newline and the rest of the sentences. The rest of the sentences start with a capital letter, beginnings of sentences, names and acronyms are capitalized and each sentence ends with a period. + ## Naming convention ### Network