|
| 1 | +<!-- |
| 2 | +Licensed to the Apache Software Foundation (ASF) under one |
| 3 | +or more contributor license agreements. See the NOTICE file |
| 4 | +distributed with this work for additional information |
| 5 | +regarding copyright ownership. The ASF licenses this file |
| 6 | +to you under the Apache License, Version 2.0 (the |
| 7 | +"License"); you may not use this file except in compliance |
| 8 | +with the License. You may obtain a copy of the License at |
| 9 | +
|
| 10 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | +
|
| 12 | +Unless required by applicable law or agreed to in writing, |
| 13 | +software distributed under the License is distributed on an |
| 14 | +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | +KIND, either express or implied. See the License for the |
| 16 | +specific language governing permissions and limitations |
| 17 | +under the License. |
| 18 | +--> |
| 19 | + |
| 20 | +# Contributing to Apache DataFusion Java |
| 21 | + |
| 22 | +Bug reports, design discussion, and patches are welcome. This project follows |
| 23 | +the Apache DataFusion contribution model. |
| 24 | + |
| 25 | +## Filing issues and discussing changes |
| 26 | + |
| 27 | +- File bugs and feature requests on [GitHub issues](https://github.com/apache/datafusion-java/issues). |
| 28 | +- For larger or design-level discussion, the mailing list is |
| 29 | + [dev@datafusion.apache.org](mailto:dev@datafusion.apache.org). |
| 30 | +- Please open an issue before sending a PR for any significant change so the |
| 31 | + approach can be agreed on first. |
| 32 | + |
| 33 | +## Development workflow |
| 34 | + |
| 35 | +Branch from `main`, write changes with [conventional commit](https://www.conventionalcommits.org/) |
| 36 | +messages in the imperative mood (e.g. `feat: add foo`, `fix(native): handle bar`), |
| 37 | +and open a pull request targeting `main`. |
| 38 | + |
| 39 | +The first build in a fresh checkout reaches out to `raw.githubusercontent.com` |
| 40 | +to fetch the DataFusion protobuf schemas (see *Updating the DataFusion / |
| 41 | +protobuf schema version* below). Subsequent builds are offline — the |
| 42 | +`download-maven-plugin` cache under `~/.m2/repository/.cache/` satisfies them. |
| 43 | + |
| 44 | +## Code style |
| 45 | + |
| 46 | +- Java: run `./mvnw spotless:apply` before committing. CI fails the build if |
| 47 | + formatting drifts. |
| 48 | +- Rust: run `cargo fmt` and `cargo clippy --all-targets -- -D warnings` inside |
| 49 | + `native/`. |
| 50 | +- New source files need the Apache 2.0 license header. Apache RAT enforces this |
| 51 | + during `verify`. |
| 52 | + |
| 53 | +## Updating the DataFusion / protobuf schema version |
| 54 | + |
| 55 | +Three things must move together when bumping DataFusion: |
| 56 | + |
| 57 | +1. `native/Cargo.toml` — the `datafusion` crate dependency. |
| 58 | +2. `pom.xml` — the `<datafusion.version>` Maven property. **Must equal the |
| 59 | + Cargo version**; a mismatch means JVM-built protobuf plans won't deserialize |
| 60 | + on the native side. |
| 61 | +3. `pom.xml` — the `<sha512>` checksums on the two `download-maven-plugin` |
| 62 | + executions. These pin the downloaded `.proto` files; the build fails if |
| 63 | + upstream silently re-tags them, which is the desired behavior. |
| 64 | + |
| 65 | +Recipe: |
| 66 | + |
| 67 | +```sh |
| 68 | +# 1. Bump the Cargo dep |
| 69 | +$EDITOR native/Cargo.toml # set datafusion = "<new>" |
| 70 | +(cd native && cargo update -p datafusion) |
| 71 | + |
| 72 | +# 2. Bump the Maven property to match |
| 73 | +$EDITOR pom.xml # set <datafusion.version> |
| 74 | + |
| 75 | +# 3. Compute the new SHA-512 hashes for both `.proto` files from the upstream |
| 76 | +# tag you just set in step 2, then paste them into the two <sha512> elements |
| 77 | +# in pom.xml. |
| 78 | +NEW=$(grep -m1 -oE '<datafusion.version>[^<]+' pom.xml | cut -d'>' -f2) |
| 79 | +curl -sL "https://raw.githubusercontent.com/apache/datafusion/$NEW/datafusion/proto-common/proto/datafusion_common.proto" | shasum -a 512 | awk '{print $1}' |
| 80 | +curl -sL "https://raw.githubusercontent.com/apache/datafusion/$NEW/datafusion/proto/proto/datafusion.proto" | shasum -a 512 | awk '{print $1}' |
| 81 | +$EDITOR pom.xml # paste the two hashes into the <sha512> elements |
| 82 | + |
| 83 | +# Drop the local download cache so the next build re-downloads against the new hashes. |
| 84 | +rm -rf ~/.m2/repository/.cache/download-maven-plugin target/proto |
| 85 | + |
| 86 | +# 4. Verify |
| 87 | +make && make test |
| 88 | +``` |
| 89 | + |
| 90 | +The protobuf runtime version (`<protobuf.version>` in `pom.xml`) tracks the |
| 91 | +Java ecosystem (security and JDK compatibility), not DataFusion. Bump it |
| 92 | +independently when there is a reason. |
0 commit comments