Skip to content

Inconsistent format of description of flags (starting with lowercase letter) #10454

Closed
#10507
Closed
Inconsistent format of description of flags (starting with lowercase letter)#10454
#10507
Assignees
williammartin
Labels
bugSomething isn't workinghelp wantedContributions welcomepriority-3Affects a small number of users or is largely cosmetic

Description

@iamazeem
iamazeem
opened on Feb 16, 2025

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:

21 results - 13 files

pkg/cmd/extension/command.go:
  414: 			cmd.Flags().BoolVar(&forceFlag, "force", false, "force upgrade extension, or ignore if latest already installed")
  415: 			cmd.Flags().StringVar(&pinFlag, "pin", "", "pin extension to a release tag or commit ref")
  529: 			cmd.Flags().BoolVar(&debug, "debug", false, "log to /tmp/extBrowse-*")

pkg/cmd/gist/delete/delete.go:
  74: 	cmd.Flags().BoolVar(&opts.Confirmed, "yes", false, "confirm deletion without prompting")

pkg/cmd/gpg-key/delete/delete.go:
  52: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")

pkg/cmd/issue/delete/delete.go:
  60: 	cmd.Flags().BoolVar(&opts.Confirmed, "confirm", false, "confirm deletion without prompting")
  61: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")
  62: 	cmd.Flags().BoolVar(&opts.Confirmed, "yes", false, "confirm deletion without prompting")

pkg/cmd/issue/develop/develop.go:
  123: 	_ = cmd.Flags().MarkDeprecated("issue-repo", "use `--repo` instead")

pkg/cmd/label/delete.go:
  56: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")

pkg/cmd/repo/archive/archive.go:
  63: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")

pkg/cmd/repo/delete/delete.go:
  68: 	cmd.Flags().BoolVar(&opts.Confirmed, "confirm", false, "confirm deletion without prompting")
  69: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")
  70: 	cmd.Flags().BoolVar(&opts.Confirmed, "yes", false, "confirm deletion without prompting")

pkg/cmd/repo/list/list.go:
  111: 	_ = cmd.Flags().MarkDeprecated("public", "use `--visibility=public` instead")
  112: 	_ = cmd.Flags().MarkDeprecated("private", "use `--visibility=private` instead")

pkg/cmd/repo/rename/rename.go:
  102: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")

pkg/cmd/repo/setdefault/setdefault.go:
  108: 	cmd.Flags().BoolVarP(&opts.ViewMode, "view", "v", false, "view the current default repository")
  109: 	cmd.Flags().BoolVarP(&opts.UnsetMode, "unset", "u", false, "unset the current default repository")

pkg/cmd/repo/unarchive/unarchive.go:
  62: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")

pkg/cmd/ssh-key/delete/delete.go:
  52: 	_ = cmd.Flags().MarkDeprecated("confirm", "use `--yes` instead")

Affected version

$ gh --version 
gh version 2.67.0 (2025-02-11)
https://github.com/cli/cli/releases/tag/v2.67.0

Steps to reproduce the behavior

  • Search codebase with regex cmd.Flags().*, "[a-z]+ .*"\)

Expected vs actual behavior

The descriptions in above cases should also start with an uppercase letter.

Logs

N/A

Activity

  1. iamazeem
    added
    bugSomething isn't working
    on Feb 16, 2025
  2. cliAutomation
    added
    needs-triageneeds to be reviewed
    on Feb 16, 2025
  3. iamazeem
    changed the title [-]Inconsistent format for flags description text[/-] [+]Inconsistent format of description of flags (starting with lowercase letter)[/+] on Feb 16, 2025

  4. williammartin commented on Feb 17, 2025

    @williammartin
    williammartin
    on Feb 17, 2025
    Member

    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.

  5. williammartin
    added
    priority-3Affects a small number of users or is largely cosmetic
    help wantedContributions welcome
    and removed
    needs-triageneeds to be reviewed
    on Feb 17, 2025

  6. iamazeem commented on Feb 18, 2025

    @iamazeem
    iamazeem
    on Feb 18, 2025
    ContributorAuthor

    Hey @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.
    The Usage field of all the flags can be transformed at runtime.

    For example, in pkg/cmd/root/root.go, it can be done recursively using spf13/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)
+ 	}
+ }

  7. williammartin commented on Feb 18, 2025

    @williammartin
    williammartin
    on Feb 18, 2025
    Member

    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?

  8. williammartin
    self-assigned this
    on Feb 18, 2025

  9. iamazeem commented on Feb 18, 2025

    @iamazeem
    iamazeem
    on Feb 18, 2025
    ContributorAuthor

    @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.

  10. williammartin
    closed this as completedin #10507on Feb 27, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workinghelp wantedContributions welcomepriority-3Affects a small number of users or is largely cosmetic

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions