How to contribute

This section collects everything a new contributor needs to ship a change to cli/cli. The authoritative source is .github/CONTRIBUTING.md; this wiki summarises and groups it.

At a glance

1. Pick up work. New commands need triage approval (see docs/working-with-us.md). Bug fixes can go straight to a PR.
2. Branch off trunk. PRs target the trunk branch.
3. Implement using the Options + Factory pattern. Every command has NewCmdFoo(f *cmdutil.Factory, runF func(*FooOptions) error) plus a separate fooRun(opts) for the business logic. See Patterns and conventions.
4. Cover with tests. HTTP via httpmock.Registry, terminal via iostreams.Test(), prompts via the Prompter mock. See Testing.
5. Run the gates. go test ./... and make lint must pass before commit. The CI workflows in .github/workflows/ re-run both.
6. Open a PR. The triage workflow (.github/workflows/triage-pull-requests.yml) labels and routes it. Reviews go to @cli/code-reviewers plus any subsystem owners listed in .github/CODEOWNERS.

Definition of done

• New behaviour has unit tests; HTTP-touching code uses httpmock and defer reg.Verify(t) to assert all stubs were hit.
• Feature-detected branches carry a // TODO <cleanupIdentifier> comment, otherwise the lint fails.
• Public Go symbols have godoc comments. Do not restate behaviour in inline comments.
• No em dashes (-) anywhere in code, comments, or docs.
• Help text uses heredoc.Doc and matches the # comment plus $ command example style.
• If your change adds a new top-level command, register it in pkg/cmd/root/root.go and update the relevant help group.

Sub-pages

• Development workflow - branches, commits, the merge cycle.
• Testing - frameworks, mocks, table-driven patterns.
• Debugging - logs, common errors, environment variables.
• Patterns and conventions - the Options + Factory pattern, error types, JSON output flags.
• Tooling - lint, build, generate, manpages, and CI.