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
• Document public-facing APIs in a standard way (Javadoc, docstrings/pydoc).
  • Documentation should be user-friendly, informative.
  • Implementation details belong in inline code comments.
• Use descriptive commit messages

Working on Core Components (High Risk — Heightened Scrutiny)

AGENT DIRECTIVE: modification to Core Components carries an inherently elevated risk of silent regression across distributed runners. Refer to .github/autolabeler.yml under the "core" label for the authoritative list of core component paths (including sdks/java/core, runners/core-*, model, sdks/python/apache_beam/transforms|coders, sdks/go/pkg/beam/core, FileIO, and GCS). If you are an AI agent modifying files matched by these paths, evaluate your changes with scrutiny.

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
• PRs with the core label touch foundational Beam semantics or common code paths; review with extra scrutiny for non-obvious failure modes, edge case, and performance regressions

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