Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
194 lines (136 loc) · 6.71 KB

CONTRIBUTING.md

File metadata and controls

194 lines (136 loc) · 6.71 KB
Raw

Contributing to Pulumi Java

Thank you for contributing to help make Pulumi Java support better. We appreciate the help! This repository is one of many across the Pulumi ecosystem and we welcome contributions to them all.

Code of Conduct

Please make sure to read and observe our Contributor Code of Conduct.

Communications

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.

Issues

Feel free to pick up any existing issue that looks interesting to you or fix a bug you stumble across while using Pulumi with Java. No matter the size, we welcome all improvements.

Feature Work

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.

Developing

Setting up your development environment

This repo uses mise to manage tool versions (Go, JDK, Gradle, Maven, etc.). Install mise and run mise install to get the correct versions. See .mise.toml for the full list.

You will also need:

  • Pulumi CLI 3.30.0 or higher

Preparing a pull request

  1. Ensure running make passes with no issues.
  2. Run make codegen_tests_update if anything related to codegen has been changed.
  3. We 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.

Understanding the repo structure

  • sdk/java/ is a Gradle project that hosts the core Java SDK

  • pkg/cmd/pulumi-language-java is a Go program that defines the Pulumi Java Language Provider

  • pkg/codegen hosts Java SDK and program generation Go packages

  • tests/examples contain a few example programs and Go test automation that exercises them regularly in a CI context

  • pulumi is a Git submodule reference to a copy of pulumi/pulumi with the purpose of consuming protobuf definitions that declare SDK and provider interfaces

Working with local dependencies

There are Make targets that help rebuild all Java and Go packages from source. For correct cross-referencing in examples and tests, Java packages need to be installed into the local ~/.m2 Maven repo.

The targets do not yet understand dependencies accurately, so you may need to re-run to make sure changes to Java SDK or providers are rebuilt.

As for Go changes, Pulumi CLI will respect the version of pulumi-language-java it finds in PATH over the default version it ships with. When testing changes to the language provider, you therefore might need to manipulate PATH to prefer the locally build version.

make submodule_update # downloads pulumi/pulumi for protobuf definitions
make install_sdk # installs com.pulumi:pulumi into ~/.m2 maven repo
make bin/pulumi-language-java # builds bin/pulumi-language-java language host
export PATH="${PATH}:${PWD}/bin" # add bin/pulumi-language-java to PATH

Updating generated test code

The pkg/codegen/testing/test/testdata directory holds generated code used in tests. Tests will begin failing if the code in this directory is out-of-date.

Use make codegen_tests_update to update code it if you change any codegen logic.

Working with published dependencies

Release builds of the Java SDK are published to Maven Central as com.pulumi:pulumi.

Adding examples and testing them locally

Every example is a valid Pulumi program that can be tested by manually doing pulumi up in the right folder.

cd tests/examples/aws-java-webserver
pulumi up

Manual testing sometimes requires setting per-example settings using pulumi config and is documented in every individual example README.md.

For automated testing, examples are added to java_examples_test.go to run under ProgramTest framework. There is a Make helper to run the automated test:

make test_example.aws-java-webserver

Testing templates locally

See templates/README.md on how to manually test template changes locally.

Similarly to examples, Make helper targets are provided to automatically test templates, for example to test templates/java-gradle run:

make test_template.java-gradle

Getting Help

We are 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.

Changelog

Changelog management is done via changie. See the installation guide for changie.

Always use make changelog (or changie new) to create entries. Do not hand-write the YAML files in .changes/unreleased/: the rendered changelog embeds the pull request number from custom.PR, and omitting it causes links to render as <no value>.

Here is an example of what make changelog looks like:

$ make changelog
✔ Component … sdk
✔ Kind … Improvements
✔ Body … Cool new SDK feature.
✔ GitHub Pull Request … 123

Changelog messages

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

Release Process

Releases are prepared automatically every Monday at 09:00 UTC. If there are unreleased changelog entries, the automation:

  1. Runs changie batch auto to choose the next version from the change kinds, then changie merge to update CHANGELOG.md.
  2. Opens or updates a Changelog for v<version> PR from automation/next-release containing the versioned changelog and updated CHANGELOG.md.
  3. Approves the PR and enables squash auto-merge, so it merges once the required checks pass.

Merging the release PR triggers this repository's release workflow, which creates the GitHub release, publishes the Java SDK to Maven Central, pushes the v* and sdk/v* tags, and triggers the SDK documentation update.