| --- |
| # Licensed to the Apache Software Foundation (ASF) under one |
| # or more contributor license agreements. See the NOTICE file |
| # distributed with this work for additional information |
| # regarding copyright ownership. The ASF licenses this file |
| # to you under the Apache License, Version 2.0 (the |
| # "License"); you may not use this file except in compliance |
| # with the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, |
| # software distributed under the License is distributed on an |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| # KIND, either express or implied. See the License for the |
| # specific language governing permissions and limitations |
| # under the License. |
| |
| name: contributing |
| description: Guides the contribution workflow for Apache Beam, including creating PRs, issue management, code review process, and release cycles. Use when contributing code, creating PRs, or understanding the contribution process. |
| --- |
| |
| # 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) |
| ```bash |
| ./local-env-setup.sh |
| ``` |
| |
| #### Docker-based Setup |
| ```bash |
| ./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](https://s.apache.org/beam-design-doc-template) |
| - Review [existing design docs](https://s.apache.org/beam-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](https://home.apache.org/phonebook.html?pmc=beam) |
| |
| ## Testing Workflows |
| |
| ### Pre-commit Tests |
| Run automatically on PRs. To run locally: |
| ```bash |
| ./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](https://github.com/apache/beam/blob/master/.test-infra/jenkins/README.md). |
| |
| ## Formatting |
| |
| ### Java |
| ```bash |
| ./gradlew spotlessApply |
| ``` |
| |
| ### Python |
| ```bash |
| # Uses yapf, isort, pylint |
| pre-commit run --all-files |
| ``` |
| |
| ### CHANGES.md |
| ```bash |
| ./gradlew formatChanges |
| ``` |
| |
| ## Release Cycle |
| - Minor releases every 6 weeks |
| - Check [release calendar](https://calendar.google.com/calendar/embed?src=0p73sl034k80oob7seouanigd0%40group.calendar.google.com) |
| - 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](https://beam.apache.org/contribute/) |
| - [PTransform Style Guide](https://beam.apache.org/contribute/ptransform-style-guide) |
| - [Runner Authoring Guide](https://beam.apache.org/contribute/runner-guide/) |
| - [Wiki Tips](https://cwiki.apache.org/confluence/display/BEAM/) |
| - [Git Tips](https://cwiki.apache.org/confluence/display/BEAM/Git+Tips) |
| - [Java Tips](https://cwiki.apache.org/confluence/display/BEAM/Java+Tips) |
| - [Python Tips](https://cwiki.apache.org/confluence/display/BEAM/Python+Tips) |
| - [Go Tips](https://cwiki.apache.org/confluence/display/BEAM/Go+Tips) |
| - [Gradle Tips](https://cwiki.apache.org/confluence/display/BEAM/Gradle+Tips) |
| |
| ## Communication |
| - User mailing list: user@beam.apache.org |
| - Dev mailing list: dev@beam.apache.org |
| - Slack: [#beam channel](https://s.apache.org/beam-slack-channel) |
| - Issues: https://github.com/apache/beam/issues |
