Abacn commented on code in PR #30879: URL: https://github.com/apache/beam/pull/30879#discussion_r1567920232
########## contributor-docs/code-change-guide.md: ########## @@ -0,0 +1,519 @@ +<!-- +Licensed 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. +--> + +This guide is for Beam users and developers changing and testing Beam code. +Specifically, this guide provides information about: + +1. Testing code changes locally + +2. Building Beam artifacts with modified Beam code and using the modified code for pipelines + +# Repository structure + +The Apache Beam GitHub repository (Beam repo) is, for the most part, a "mono repo": +it contains everything in the Beam project, including the SDK, test +infrastructure, dashboards, the [Beam website](https://beam.apache.org), +the [Beam Playground](https://play.beam.apache.org), and so on. + +## Gradle quick start + +The Beam repo is a single Gradle project that contains all components, including Python, +Go, the website, etc. It is useful to familiarize yourself with the Gradle project structure: +https://docs.gradle.org/current/userguide/multi_project_builds.html + +### Gradle key concepts + +Grade uses the following key concepts: + +* **project**: a folder that contains the `build.gradle` file +* **task**: an action defined in the `build.gradle` file +* **plugin**: runs in the project's `build.gradle` and contains predefined tasks and hierarchies + +For example, common tasks for a Java project or subproject include: + +- `compileJava` +- `compileTestJava` +- `test` +- `integrationTest` + +To run a Gradle task, the command is `./gradlew -p <project path> <task>` or `./gradlew :project:path:task_name`. For example: + +``` +./gradlew -p sdks/java/core compileJava + +./gradlew :sdks:java:harness:test +``` + +### Gradle project configuration: Beam specific + +* A **huge** plugin `buildSrc/src/main/groovy/org/apache/beam/gradle/BeamModulePlugin` manages everything. + +In each java project or subproject, the `build.gradle` file starts with: + +```groovy + +apply plugin: 'org.apache.beam.module' + +applyJavaNature( ... ) +``` + +Relevant usage of `BeamModulePlugin` includes: +* Manage Java dependencies +* Configure projects (Java, Python, Go, Proto, Docker, Grpc, Avro, an so on) + * Java -> `applyJavaNature`; Python -> `applyPythonNature`, and so on + * Define common custom tasks for each type of project + * `test`: run Java unit tests + * `spotlessApply`: format java code + +## Code paths + +The following are example code paths relevant for SDK development: + +* `sdks/java` Java SDK + * `sdks/java/core` Java core + * `sdks/java/harness` SDK harness (entrypoint of SDK container) + +* `runners` runner supports, written in Java. For example, Review Comment: Added this information to code path: "Java code paths are mainly found in two directories:" ... "For SDKS in other language, all relevant files are in `sdks/LANG`, for example," ... -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: github-unsubscr...@beam.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
