Repository navigation
Inconsistent format of description of flags (starting with lowercase letter) #10454
Description
Activity
- changed the title
[-]Inconsistent format for flags description text[/-][+]Inconsistent format of description of flags (starting with lowercase letter)[/+]on Feb 16, 2025 Makes sense to me, thanks for your diligence.
Acceptance Criteria
When I provide a --help flag to any command
Then the flag description always starts with an uppercase letter
Like #10449 I wonder whether we could add a linting rule for this.
Reacted by AzeemHey @williammartin,
Looked into its linting by parsing the AST with a script but seemed a bit involved i.e. a new script, integration with CI pipeline, etc.
Seemed like another thing to maintain and update, not to mention the failed workflows on linting errors and other overheads.Thought about automating it and that seemed more feasible.
TheUsagefield of all the flags can be transformed at runtime.For example, in
pkg/cmd/root/root.go, it can be done recursively usingspf13/pflag#VisitAll:+ transformFlagUsages(cmd) return cmd, nil } + func transformFlagUsages(cmd *cobra.Command) { + cmd.Flags().VisitAll(func(flag *pflag.Flag) { + if len(flag.Usage) > 0 && unicode.IsLower(rune(flag.Usage[0])) { + flag.Usage = strings.ToUpper(flag.Usage[:1]) + flag.Usage[1:] + } + }) + + for _, subCmd := range cmd.Commands() { + transformFlagUsages(subCmd) + } + }
Hmm yeh, adding a custom golangci-linter is quite a pain. I made an example here which produces:
Use "golangci-lint [command] --help" for more information about a command. ➜ cli git:(trunk) ✗ ./custom-gcl run pkg/cmd/codespace/create.go:116:79: Cobra flag help text should start with a capital letter. (cobrahelpcasing) createCmd.Flags().StringVar(&opts.devContainerPath, "devcontainer-path", "", "path to the devcontainer.json file to use when creating codespace") ^ pkg/cmd/codespace/edit.go:37:66: Cobra flag help text should start with a capital letter. (cobrahelpcasing) editCmd.Flags().StringVar(&opts.displayName, "displayName", "", "display name") ^ pkg/cmd/codespace/rebuild.go:38:58: Cobra flag help text should start with a capital letter. (cobrahelpcasing) rebuildCmd.Flags().BoolVar(&fullRebuild, "full", false, "perform a full rebuild") ^ pkg/cmd/extension/command.go:414:52: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&forceFlag, "force", false, "force upgrade extension, or ignore if latest already installed") ^ pkg/cmd/extension/command.go:415:47: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().StringVar(&pinFlag, "pin", "", "pin extension to a release tag or commit ref") ^ pkg/cmd/extension/command.go:529:48: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&debug, "debug", false, "log to /tmp/extBrowse-*") ^ pkg/cmd/gist/delete/delete.go:74:53: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&opts.Confirmed, "yes", false, "confirm deletion without prompting") ^ pkg/cmd/issue/delete/delete.go:60:57: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&opts.Confirmed, "confirm", false, "confirm deletion without prompting") ^ pkg/cmd/issue/delete/delete.go:62:53: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&opts.Confirmed, "yes", false, "confirm deletion without prompting") ^ pkg/cmd/repo/delete/delete.go:68:57: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&opts.Confirmed, "confirm", false, "confirm deletion without prompting") ^ pkg/cmd/repo/delete/delete.go:70:53: Cobra flag help text should start with a capital letter. (cobrahelpcasing) cmd.Flags().BoolVar(&opts.Confirmed, "yes", false, "confirm deletion without prompting")It seems more effort than it is worth. It's a bit surprising to me that there is no inbuilt linter for regexes.
Re: runtime transformation, I'm generally just a bit nervous about these kind of approaches because it's spooky action at a distance. Some maintainer in the future is going to wonder how the first letter is being capitalised, and the trail is not obvious. What are your thoughts?
@williammartin: I agree that it may add confusion later. 🤔
I think that for now these discrepancies may be fixed manually.
In addition, it may be added to the style guide.
Currently, the style guide is only mentioned in the context of proposing a design in the CONTRIBUTING doc.
That may also be updated for general PRs and reviews.
Describe the bug
Most of the descriptions for flags start with an uppercase letter.
Following are a few cases where it starts with a lowercase letter:
Affected version
Steps to reproduce the behavior
cmd.Flags().*, "[a-z]+ .*"\)Expected vs actual behavior
The descriptions in above cases should also start with an uppercase letter.
Logs
N/A