First, thanks for contributing to Pulumi and helping make it better. We appreciate the help! This repository is one of many across the Pulumi ecosystem and we welcome contributions to them all.
Please make sure to read and observe our Contributor Code of Conduct.
You are welcome to join the Pulumi Community Slack for questions and a community of like-minded folks. We discuss features and file bugs on GitHub via Issues as well as Discussions. You can read about our public roadmap on the Pulumi blog.
Feel free to pick up any existing issue that looks interesting to you or fix a bug you stumble across while using Pulumi. No matter the size, we welcome all improvements.
For larger features, we'd appreciate it if you open a new issue before investing a lot of time so we can discuss the feature together. Please also be sure to browse current issues to make sure your issue is unique, to lighten the triage burden on our maintainers. Finally, please limit your pull requests to contain only one feature at a time. Separating feature work into individual pull requests helps speed up code review and reduces the barrier to merge.
Please see the developer docs for instructions.
For contributors we use the standard fork based workflow: Fork this repository, create a topic branch, and when ready, open a pull request from your fork.
Before you open a pull request, make sure all lint checks pass:
make lintIf you see formatting failures, fix them with make format. To format a single file or directory directly:
golangci-lint fmt path/to/file.go
# or
golangci-lint fmt path/to/dirWe require a changelog entry for all PRs that aren't labeled impact/no-changelog-required. To generate a new changelog entry, run…
make changelog…and follow the prompts on screen. This requires changie to be installed. If you use mise, it is included in .mise.toml and will be installed automatically. Otherwise, install it manually (brew install changie on macOS, or go install github.com/miniscruff/changie@v1.21 otherwise).
Write clear, informative PR descriptions that help reviewers understand your changes and provide effective feedback. A good PR description serves as documentation for your changes and helps maintainers understand the impact and context.
Important: We use squash merge, so your PR description will become the git commit message. Write it accordingly.
The PR description should include:
- What: A clear summary of what changes are being made (often the PR title is sufficient)
- Why: The motivation, context, or problem being solved. This is the most important part of the description.
- How: Optionally a brief explanation of the approach taken (if not obvious). For detailed implementation explanations, consider adding comments in the code instead.
- References: Links to related issues, RFCs, or previous PRs
For PR titles, follow the same guidelines as changelog messages. Use the active imperative form and be descriptive about what the change accomplishes.
Changelog notes are written in the active imperative form. They should not end with a period. The simple rule is to pretend the message starts with "This change will ..."
Good examples for changelog entries are:
- Exit immediately from state edit when no change was made
- Fix root and program paths to always be absolute
Here are some examples of what we're trying to avoid:
- Fixes a bug
- Adds a feature
- Feature now does something
Keep changelog messages short and to the point, one sentence is usually enough. Don't overdescribe a feature in the changelog, to keep the whole log scannable quickly by end users.
Artifacts built during pull request workflows can be downloaded by running the following command (note that the artifacts expire 7 days after CI has been run):
curl -fsSL https://get.pulumi.com | sh -s -- --version pr#<number>Pulumi employees have write access to Pulumi repositories and should push directly to branches rather than forking the repository. Tests can run directly without approval for PRs based on branches rather than forks.
Please ensure that you nest your branches under a unique identifier such as your name (e.g. refs/heads/pulumipus/cool_feature).
The Pulumi system is robust and offers many features that might seem overwhelming at first. To assist you in getting started, our team has put together the Pulumi Developer Documentation. This resource provides valuable insights into how the system is structured and can be incredibly helpful for both new contributors and maintainers alike. We encourage you to explore it and reach out if you have any questions!
We're sure there are rough edges and we appreciate you helping out. If you want to talk with other folks in the Pulumi community (including members of the Pulumi team) come hang out in the #contribute channel on the Pulumi Community Slack.
If you're using an AI coding assistant to contribute:
- Read
AGENTS.mdat the repo root for the full command canon and invariants. - Understand the existing code before proposing changes — read relevant files first.
- Make minimal, scoped changes. Don't refactor unrelated code or add unnecessary abstractions.
- Run
make format && make lint && make test_fastand fix all failures before submitting. - Include actual test output in your PR description (copy-paste, don't paraphrase).
- Don't forget the changelog entry (
make changelog).
Note that we expect contributors using AI to remain in the loop. This means that any content generated with AI (whether code or text) must have been reviewed and edited by a human before submission, and that the human involved retains responsibility for their output. You are expected to be able to explain your changes and how they interact with the system at large.
Whenever a new PR is merged in this repository, the latest draft release on the GitHub Releases page is updated with the latest binaries. To release one of those draft releases a few steps are necessary:
A weekly job runs every Wednesday. It bumps sdk/.version to the next minor version and opens a PR containing the changelog the release is expected to publish, which is approved and queued to merge automatically. Merging that PR "freezes" the draft release for the previous version, which is the one we are about to publish.
To cut a patch release instead, bump sdk/.version to the next patch version by hand using scripts/set-version.py <next-patch-version>, and merge that.
The next step, to gain some additional confidence in the release is to run the Test examples, and Test templates test suites. These run the tests in the pulumi/examples and pulumi/templates repositories using the latest pulumi/pulumi dev version, thus including all the latest changes.
Finally to create the release, navigate to the GitHub Releases page and edit the release of the version we froze just before. Untick "Set as a pre-release", and tick both "Set as the latest release" and "Create a discussion for this release" in the "Releases" category at the bottom of the page, before clicking "Publish release".
Caution
Double-check the version number of the release. The most recent release in the releases list tracks changes to master, and might not be the one you want to release if PRs have been merged since the freeze. For this reason, the version you want to release may be the second one in the list. The version should be the one that was in sdk/.version before the freeze PR was merged.
Finally pulumi-bot will create another PR to update with go.mod updates and changelog cleanups. This PR is approved and queued to merge automatically.