Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
96 lines (67 loc) · 4.47 KB

CONTRIBUTING.md

File metadata and controls

96 lines (67 loc) · 4.47 KB
Raw

Contributing to the Pulumi ecosystem

Do you want to contribute to Pulumi? Awesome! We are so happy to have you. We have a few tips and housekeeping items to help you get up and running.

Code of Conduct

Please make sure to read and observe our Code of Conduct

Community Expectations

Please read about our contribution guidelines here.

Setting up your development environment

Pulumi prerequisites

Please refer to the main Pulumi repo's CONTRIBUTING.md file for details on how to get set up with Pulumi.

Committing Generated Code

You must generate and check in the SDKs on each pull request containing a code change, e.g. adding a new resource override to provider/resource_overrides.go.

  1. Run make schema && make provider to regenerate schema artifacts and the provider binary.
  2. Run make build_sdks from the root of this repository (this regenerates SDK artifacts as needed).
  3. Open a pull request containing all changes.
  4. Note: If a large number of seemingly-unrelated diffs are produced by make build_sdks (for example, lots of changes to comments unrelated to the change you are making), ensure that the latest dependencies for the provider are installed by running go mod tidy in the provider/ directory of this repository.

Local Verification Loop

For most provider-code changes, run this loop before opening a pull request:

  1. make lint
  2. make test_provider
  3. If schema-affecting files changed (for example provider/resources.go, override files, overlays, or token mappings), also run:
    • make schema
    • make build_sdks

AI-Assisted Contributions

If you are using an AI coding assistant:

  1. Read AGENTS.md first.
  2. Keep changes scoped and avoid unrelated refactors.
  3. Do not manually edit generated files under sdk/.
  4. Include exact validation commands and outcomes in the pull request description.

Carrying Upstream Patches

Upstream patches add recurring upgrade cost and can create behavior that Pulumi must maintain indefinitely. Before contributing one, follow docs/upstream-patches.md for patch policy and Pulumi AWS-specific tracking, test, CI, and AWS safety requirements. Use the upstream-patches skill for patch mechanics.

Do not treat a patch applying cleanly as sufficient validation.

Testing

See TESTING.md to choose the lowest-cost test that proves the behavior, use the repository's test helpers, and run focused tests.

The examples/ package mixes live AWS tests, recorded provider-upgrade tests, and local checks. Do not run unfiltered make test unless you intend to run the full acceptance suite. For a live test, configure Pulumi with AWS, set AWS_REGION, inspect the fixture and cleanup path, and run only the named test. Failed cleanup may require manual removal of AWS resources.

Generating IAM Policies

aws iam list-policies --scope AWS | jq -f docs/generate-iam-policies.jq -r > policies.go

Copy the content of policies.go and insert into the iam_managed_policy.go file, merging with any existing manual changes. If policies have been removed, we should keep them but mark them as deprecated.

Updating pulumi-terraform-aws dependency

Keeping the pulumi-terraform-aws dependency up-to-date involves updating the ./upstream Git sub-module, resolving patch conflicts, adjusting provider overrides and token mappings, and re-generating the SDKs. For a fully worked example, to update to v5.60.0 (actual update in #4309):

git branch upstream-v5.60.0 && git checkout upstream-v5.60.0
./scripts/upstream.sh checkout
./scripts/upstream.sh rebase -o v5.60.0
# in ./rebase finish the Git rebase and resolve conflicts
(cd ./upstream && go build ./...) # verify everything builds
# add commits as needed to make it build
./scripts/upstream.sh check_in
git add ./patches && git commit -m "Update patches for v5.60.0"
(cd upstream && git reset --hard v5.60.0)
git add ./upstream && git commit -m "Move upstream to v5.60.0"
./scripts/upstream.sh init -f # verify patches apply cleanly with no changes
./scripts/tidy-all.sh
git add . && git commit -m "./scripts/tidy-all.sh"
make tfgen # iterate on editing provider overrides and token mappings as needed
git add . && git commit -m "make tfgen"
make build_sdks && git add . && git commit -m "make build_sdks"