<!--
  ~ 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.
-->

# Contributing

## Get Started
This is a Rust project, so [rustup](https://rustup.rs/) is a great place to start. It provides an easy way to manage your Rust installation and toolchains.

Rust and `cargo` are enough for the unit tests and the lint gates. Here are the
commands CI runs, which are the ones to reproduce locally:
- `cargo check`: Analyze the current package and report errors. This is a quick way to catch any obvious issues without a full compilation.
- `cargo fmt --all -- --check`: Verify the code matches the Rust style guidelines. `cargo fmt --all` rewrites the files in place.
- `cargo build`: Compile the current package. This will build the project and generate executable binaries if applicable.
- `cargo clippy --locked --all-targets --workspace --features fulltext,vortex -- -D warnings`: Catch common mistakes and improve code quality. CI denies warnings, so anything clippy reports fails the build.
- `cargo test -p paimon --all-targets --features fulltext,vortex`: Run the unit tests. Prefer this over a bare `cargo test`, which also builds the Python binding and can fail to link `libpython` on some platforms.
- `cargo test -p paimon-rest-server --all-targets`: Run the REST server tests.

The integration suites additionally need a Paimon warehouse written by Spark, so
they are not pure `cargo`:

```bash
make docker-up    # builds the Spark image and writes /tmp/paimon-warehouse
cargo test -p paimon-integration-tests --all-targets
cargo test -p paimon-datafusion --all-targets
make docker-down  # tear down when finished
```

Without that warehouse those tests fail with `TableNotExist` rather than being
skipped. Override the location with `PAIMON_TEST_WAREHOUSE` if you need a
different path.

### Setting up the Development Environment
1. Install Rust using `rustup`. Follow the instructions on the [rustup website](https://rustup.rs/) to install Rust on your system.
2. Clone the repository to your local machine.
3. Navigate to the project directory.

### Making Changes
1. Create a new branch for your changes. This helps keep your work separate from the main development branch and makes it easier to review and merge your changes.
2. Make your changes and ensure that the code still compiles and passes all tests. Use the commands mentioned above to check for errors and run tests.
3. Format your code using `cargo fmt --all` to ensure consistency with the project's code style.

### Submitting Changes
1. Once you are satisfied with your changes, push your branch to the remote repository.
2. Open a pull request on the project's GitHub page. Provide a clear description of your changes and why they are necessary.
3. Wait for reviews and address any feedback. Once the pull request is approved and merged, your changes will be part of the project.

## AI-Assisted Contributions

Apache Paimon Rust has the following policy for AI-assisted pull requests:

- The PR author should **understand the core ideas** behind the implementation **end-to-end** and be able to justify the design and code during review.
- **Call out unknowns and assumptions.** It is acceptable not to fully understand some details of AI-generated code, but authors should identify these cases and point them out to reviewers. This allows reviewers to apply their knowledge of the codebase and evaluate potential concerns, such as correctness, concurrency, compatibility, or performance risks.

### Why fully AI-generated PRs without understanding are not helpful

AI tools cannot reliably make complex changes to Apache Paimon Rust on their own, which is why we rely on pull requests and code review.

The purposes of code review are:

1. Complete the intended task correctly.
2. Share knowledge between authors and reviewers as a long-term investment in the project.

A fully AI-generated contribution without sufficient author understanding does not meet these purposes. Maintainers could use AI tools directly, while contributors acting only as a proxy gain little knowledge of the project.

Review capacity is limited, so large pull requests that appear to lack the required understanding may not be reviewed and may eventually be closed or redirected.

### Better ways to contribute than an "AI dump"

Consider writing a high-quality issue with a clear problem statement and a minimal reproducible example. This often makes it easier for the community to investigate the problem and develop an appropriate solution.

### Read the design docs

For a deeper understanding of the project, read the design documentation available on our [Paimon Rust](https://paimon.apache.org/docs/rust/).

Thank you for contributing to this project! 😊
