How to contribute

This section tells you how to work in pulumi/pulumi — pickup, branching, lint/test, PR review, and merge. Everything here is grounded in the repo's CONTRIBUTING.md and AGENTS.md.

Picking up work

• Browse open issues — anything not labelled tracking or epic is fair game.
• Larger features: open an issue first to align on the design before writing code (per CONTRIBUTING.md).
• The public roadmap is at pulumi/pulumi#projects/44.

PR process at a glance

1. Fork (external) or create a topic branch under your name (Pulumi employees, e.g. pulumipus/cool_feature).
2. Code + tests.
3. Run make format && make lint && make test_fast before pushing.
4. Add a changelog entry: make changelog.
5. Push and open a PR. PRs are squash-merged, so your PR description becomes the commit message — write it for posterity.
6. CI runs the full matrix (.github/workflows/ci.yml).
7. A reviewer approves.
8. PR auto-merges.

The PR description rules from CONTRIBUTING.md:

• What — usually conveyed by the title.
• Why — the most important section. Explain the motivation.
• How — only if non-obvious.
• References — issues, RFCs, prior PRs.

PR titles follow the same imperative form as changelog messages. Pretend the message starts with "This change will...".

Definition of done

A change is ready to merge when:

• All affected modules' tests pass (make test_fast minimum, integration tests when relevant).
• Lint and format are clean (make lint, make format).
• A changelog entry exists in changelog/pending/ (or the PR has the impact/no-changelog-required label).
• Generated proto code is in sync (make check_proto).
• Public SDK / CLI surface changes have been escalated (see AGENTS.md "Escalate immediately if").
• The PR description has a clear "why".

What requires escalation

From AGENTS.md:

• Changes to public SDK exports (sdk/go/, sdk/nodejs/, sdk/python/).
• Changes to the public CLI command surface (pkg/cmd/pulumi/).
• Changes to engine state serialization, resource lifecycle, or emitted events.
• Changes to proto/*.proto.
• Two failed debugging attempts on a flaky test.

If in doubt, flag it in the PR description and pull in a maintainer.

Forbidden actions

• No git push --force or git reset --hard on shared branches without approval.
• No rm -rf outside scratch directories.
• Don't skip linting.
• Don't edit generated proto/code-gen output by hand — edit the source and regenerate.
• Don't add new external runtime dependencies without discussion.
• Don't paraphrase test output in PR descriptions — paste the actual output.

Sub-pages

• Development workflow — branching, commits, the inner loop.
• Testing — fast/all/conformance suites, lifecycle fuzz tests.
• Debugging — logs, plugin dlv attach, common failures.
• Patterns and conventions — error wrapping, goroutine ownership, copyright headers, etc.
• Tooling — mise, golangci-lint, biome, eslint, ruff, and the codegen pipeline.