Inconsistent format of examples in help text

[iamazeem]

Describe the bug

The format of examples is not consistent.

Here are a few examples:

cli/pkg/cmd/attestation/trustedroot/trustedroot.go

Lines 57 to 59 in b642da2

	Example: heredoc.Doc(`
	# Get a trusted_root.jsonl for both Sigstore Public Good and GitHub's instance
	gh attestation trusted-root

cli/pkg/cmd/auth/refresh/refresh.go

Lines 79 to 84 in b642da2

	Example: heredoc.Doc(`
	$ gh auth refresh --scopes write:org,read:public_key
	# => open a browser to add write:org and read:public_key scopes
	$ gh auth refresh
	# => open a browser to ensure your authentication credentials have the correct minimum scopes

cli/pkg/cmd/api/api.go

Lines 126 to 133 in b642da2

	Example: heredoc.Doc(`
	# list releases in the current repository
	$ gh api repos/{owner}/{repo}/releases
	# post an issue comment
	$ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI'
	# post nested parameter read from a file

cli/pkg/cmd/cache/list/list.go

Lines 43 to 45 in b642da2

	Example: heredoc.Doc(`
	# List caches for current repository
	$ gh cache list

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

Run commands from above examples with --help flag.

Expected vs actual behavior

A consistent format should be followed across all commands.

Suggested format:

# Description (Sentence case)
$ gh ...

Logs

N/A

[williammartin]

Makes sense to me, thanks for your diligence.

Acceptance Criteria

When I provide a --help flag to any command
Then the examples section takes the format:

# Description (Sentence case)
$ gh ...

[williammartin]

I wonder if we could add some linting rules to golangci-lint for this.

[iamazeem]

I wonder if we could add some linting rules to golangci-lint for this.

Checked the supported golangci-lint linters and none seem to support such cases.