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 by running gofumpt on your code:
$ gofumpt -w path/to/file.go
# or
$ gofumpt -w path/to/dirWe require a changelog entry for all PR that aren't labeled impact/no-changelog-required. To generate a new changelog entry, run…
$ make changelog…and follow the prompts on screen.
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's some examples of what we're trying to avoid:
- Fixes a bug
- Adds a feature
- Feature now does something
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.
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:
If sdk/.version is the version we want to release, we need to "freeze" that draft release. To do that update the version in pulumi/pulumi using scripts/set-version.py <next-patch-version>. This stops the draft release for the current version from being updated, and thus it is ready to be released.
If sdk/.version is not the version we want to release yet, usually in the case of a minor release, bump the version to the right version first, and merge that first (always using scripts/set-version.py). Once that's merged the current release can be frozen as above.
For these version bump PRs it's useful for reviewers if the expected changelog is included. This can be generated using GITHUB_REPOSITORY=pulumi/pulumi go run github.com/pulumi/go-change@v0.1.3 render, at the root of the repository.
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 needs to be approved, and will then auto-merge.