Contributing to Apache Beam

Getting Started

Prerequisites

• GitHub account

• Java JDK 11 (preferred, or 8, 17, 21)

• Latest Go 1.x

• Docker

• Python (any supported version for manual testing, all versions for running test suites)

• For large contributions: signed ICLA to Apache Software Foundation

Environment Setup Options

Local Setup (automated)

./local-env-setup.sh

Docker-based Setup

./start-build-env.sh

Contribution Workflow

1. Find or Create an Issue

• Search existing issues at https://github.com/apache/beam/issues

• Create new issue using appropriate template

2. Claim the Issue

.take-issue # Assigns issue to you .free-issue # Unassigns issue from you .close-issue # Closes the issue

3. For Large Changes

• Discuss on dev@beam.apache.org mailing list

• Create design doc using template

• Review existing design docs

4. Make Your Changes

• Every source file needs Apache license header

• New dependencies must have Apache-compatible open source licenses

• Add unit tests for your changes

• Use descriptive commit messages

5. Create Pull Request

• Link to the issue in PR description

• Pre-commit tests run automatically

• If tests fail unrelated to your change, comment: retest this please

6. Code Review

• Reviewers are auto-assigned within a few hours

• Use R: @username to request specific reviewer

• No response in 3 days? Email dev@beam.apache.org

Code Review Best Practices

For Authors

• Provide context in issue and PR description

• Avoid huge mega-changes

• Add follow-up changes as "fixup" commits (don't squash until approved)

• Squash fixup commits after approval

For Reviewers

• PRs can only be merged by Beam committers

Testing Workflows

Pre-commit Tests

Run automatically on PRs. To run locally:

./gradlew javaPreCommit # Java ./gradlew :sdks:python:test # Python ./gradlew :sdks:go:test # Go

Post-commit Tests

Run after merge. Trigger phrases in PR comments start specific test suites. See trigger phrase catalog.

Formatting

Java

./gradlew spotlessApply

Python

Uses yapf, isort, pylint

pre-commit run --all-files

CHANGES.md

./gradlew formatChanges

Release Cycle

• Minor releases every 6 weeks

• Check release calendar

• Changes must be in master before release branch is cut

Stale PRs

• PRs become stale after 60 days of author inactivity

• Community will close stale PRs

• Authors can reopen closed PRs

Key Resources

• Contribution Guide

• PTransform Style Guide

• Runner Authoring Guide

• Wiki Tips

• Git Tips

• Java Tips

• Python Tips

• Go Tips

• Gradle Tips

Communication

• User mailing list: user@beam.apache.org

• Dev mailing list: dev@beam.apache.org

• Slack: #beam channel

• Issues: https://github.com/apache/beam/issues