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