contributing
Guides the contribution workflow for Apache Beam, including creating PRs, issue management, code review process, release cycles, and rigorous evaluation rules for high-risk core component changes. Use when contributing code, creating PRs, or modifying core Beam components.
- License 许可
- Apache-2.0
- 所属仓库
- apache/beam
- 最近更新
- 2026-11-15
- Stars
- ★ 8.7k
- Forks
- 4.8k
01 前言 Front Matter
- name
- contributing
- description
- Guides the contribution workflow for Apache Beam, including creating PRs, issue management, code review process, release cycles, and rigorous evaluation rules for high-risk core component changes. Use when contributing code, creating PRs, or modifying core Beam components.
03 SKILL.md 正文
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.ymlunder the"core"label for the authoritative list of core component paths (includingsdks/java/core,runners/core-*,model,sdks/python/apache_beam/transforms|coders,sdks/go/pkg/beam/core,FileIO, andGCS). 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: @usernameto 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
corelabel 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
./gradlew validateChanges
- Only add entries for user-facing changes; skip minor or internal changes that do not affect public API behavior (e.g., test-only updates, typos/docs, CI/build changes, internal refactors, or fixes to unreleased changes).
- Follow the template at the top of
CHANGES.md. - End each entry with an issue or PR link:
([#X](https://github.com/apache/beam/issues/X)).
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
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
04 同仓库更多 Skills
yaml-development
Guides YAML SDK development in Apache Beam, including environment setup, testing, and key concepts. Use when working with Beam YAML code in sdks/python/apache_beam/yaml/.
runners
Guides understanding and working with Apache Beam runners (Direct, Dataflow, Flink, Spark, etc.). Use when configuring pipelines for different execution environments or debugging runner-specific issues.
python-development
Guides Python SDK development in Apache Beam, including environment setup, testing, building, and running pipelines. Use when working with Python code in sdks/python/.
license-compliance
Ensures all new files include proper Apache 2.0 license headers. Use when creating any new file in the Apache Beam repository.
java-development
Guides Java SDK development in Apache Beam, including building, testing, running examples, and understanding the project structure. Use when working with Java code in sdks/java/, runners/, or examples/java/.
io-connectors
Guides development and usage of I/O connectors in Apache Beam. Use when working with I/O connectors, creating new connectors, or debugging data source/sink issues.