This is an automated email from the ASF dual-hosted git repository.
csy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/auron.git
The following commit(s) were added to refs/heads/master by this push:
new b20b4faf [AURON#1805] Add contributing guidelines (#1806)
b20b4faf is described below
commit b20b4faf200c665d7a4ffba510eeedbf45af7e39
Author: Shreyesh <[email protected]>
AuthorDate: Sun Jan 4 23:08:52 2026 -0800
[AURON#1805] Add contributing guidelines (#1806)
# Which issue does this PR close?
Closes #1805
# Rationale for this change
Auron is currently missing a contributing guide for new contributors
# What changes are included in this PR?
New contributing guide, and a reference to it on the main README
# Are there any user-facing changes?
Yes, added README
# How was this patch tested?
N/A
---------
Co-authored-by: sarangat_LinkedIn <[email protected]>
Co-authored-by: Copilot <[email protected]>
---
CONTRIBUTING.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
README.md | 4 +-
2 files changed, 294 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..64f7dbed
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,292 @@
+<!--
+- 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 to Apache Auron (Incubating)
+
+Welcome! We're excited that you're interested in contributing to Apache Auron.
This document provides guidelines and information to help you contribute
effectively to the project.
+
+## Table of Contents
+
+- [Ways to Contribute](#ways-to-contribute)
+- [Getting Started](#getting-started)
+- [Development Environment Setup](#development-environment-setup)
+- [Building the Project](#building-the-project)
+- [Before Submitting a Pull Request](#before-submitting-a-pull-request)
+- [Pull Request Guidelines](#pull-request-guidelines)
+- [Code Style and Formatting](#code-style-and-formatting)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [Communication](#communication)
+- [License](#license)
+
+## Ways to Contribute
+
+Contributions to Auron are not limited to code! Here are various ways you can
help:
+
+- **Report bugs**: File detailed bug reports with reproducible examples
+- **Suggest features**: Propose new features or improvements via GitHub issues
+- **Write code**: Fix bugs, implement features, or improve performance
+- **Review pull requests**: Help review and test PRs from other contributors
+- **Improve documentation**: Enhance README, API docs, or add examples
+- **Answer questions**: Help other users on the mailing list or GitHub
discussions
+- **Benchmark and test**: Run benchmarks and report performance results
+
+## Getting Started
+
+### Prerequisites
+
+Before contributing, ensure you have:
+
+1. **Rust (nightly)**: Install via [rustup](https://rustup.rs/)
+2. **JDK**: Version 8, 11, or 17 (set `JAVA_HOME` appropriately)
+3. **Maven**: Version 3.9.11 or higher
+4. **Git**: For version control
+
+### Fork and Clone
+
+1. Fork the [Apache Auron repository](https://github.com/apache/auron) on
GitHub
+2. Clone your fork locally:
+ ```bash
+ git clone [email protected]:<your-username>/auron.git
+ cd auron
+ ```
+3. Add the upstream repository:
+ ```bash
+ git remote add upstream [email protected]:apache/auron.git
+ ```
+
+### Stay Synchronized
+
+Keep your fork up to date with upstream:
+
+```bash
+git fetch upstream
+git checkout master
+git merge upstream/master
+```
+
+## Development Environment Setup
+
+### Rust Setup
+
+Auron uses Rust nightly. The project includes a `rust-toolchain.toml` file
that specifies the required version:
+
+```bash
+rustup show # Verify the correct toolchain is installed
+```
+
+### IDE Setup
+
+For the best development experience:
+
+- **IntelliJ IDEA**
+- **RustRover** or **VS Code with rust-analyzer**
+
+## Building the Project
+
+Auron provides a unified build script `auron-build.sh` that supports both
local and Docker-based builds.
+
+### Quick Start Build
+
+```bash
+# Local build with Spark 3.5 and Scala 2.12
+./auron-build.sh --pre --sparkver 3.5 --scalaver 2.12
+
+# Skip native build (useful for Java/Scala-only changes)
+./auron-build.sh --pre --sparkver 3.5 --scalaver 2.12 -DskipBuildNative
+```
+
+### Docker Build
+
+```bash
+# Build inside Docker container
+./auron-build.sh --docker true --image centos7 --release \
+ --sparkver 3.5 --scalaver 2.12
+```
+
+### Build Options
+
+Run `./auron-build.sh --help` to see all available options, including:
+
+- `--pre` or `--release`: Build profile
+- `--sparkver`: Spark version (3.0, 3.1, 3.2, 3.3, 3.4, 3.5)
+- `--scalaver`: Scala version (2.12, 2.13)
+- `--celeborn`, `--uniffle`, `--paimon`, `--iceberg`: Optional integrations
+- `--skiptests`: Skip unit tests (default: true)
+- `--sparktests`: Run Spark integration tests
+
+### Running Tests
+
+By default, the build script skips unit tests (`--skiptests true`). To run
them, you must explicitly set `--skiptests false`, as shown in the examples
below:
+
+```bash
+# Run all tests
+./auron-build.sh --pre --sparkver 3.5 --scalaver 2.12 --skiptests false
+
+# Run Spark unit tests
+./auron-build.sh --pre --sparkver 3.5 --scalaver 2.12 --sparktests true
+```
+
+## Before Submitting a Pull Request
+
+Before creating a PR, please:
+
+1. **Search for existing issues**: Check if someone else is already working on
this
+
+2. **Create a GitHub issue**: All contributions (including major changes)
require a GitHub issue to be created first. This allows the community to
discuss the approach and provide feedback before you invest time in
implementation.
+
+3. **For major changes, also create an AIP**: If your change is substantial
(new features, significant architectural changes, or changes affecting the
public API), you must, in addition to the GitHub issue from step 2:
+ - Use the GitHub issue to describe the problem and proposed solution
+ - Create an **Auron Improvement Plan (AIP)** document and link it from that
GitHub issue
+ - Discuss the AIP and high-level approach with the community in the GitHub
issue
+ - Wait for community feedback and consensus before starting implementation
+
+ Example AIP: [AIP-3: Introduce auron-it for Enhanced CI Integration
Testing](https://docs.google.com/document/d/1jR5VZ_uBd6Oe2x2UT_wGFzdX_xVLhORl6ghDs4f3FIw/edit?tab=t.0)
+
+4. **Keep changes focused**: Split large changes into multiple smaller PRs
when possible
+
+5. **Write tests**: Add unit tests for bug fixes and new features
+
+6. **Update documentation**: Update relevant docs if your change affects
user-facing behavior
+
+7. **Format your code**: Run the code formatter (see [Code
Style](#code-style-and-formatting))
+
+## Pull Request Guidelines
+
+### PR Title Format
+
+Use a clear, descriptive title that follows this format:
+
+```
+[AURON #<issue-number>] Brief description of the change
+```
+
+Examples:
+- `[AURON #1805] Add contributing guidelines`
+- `[AURON #123] Fix memory leak in shuffle manager`
+- `[AURON #456] Add support for new aggregate function`
+
+Note: Use the hash format `[AURON #<issue-number>]` consistently throughout
your PR title and description.
+
+### PR Size
+
+We strongly prefer smaller, focused PRs over large ones because:
+
+- Smaller PRs are reviewed more quickly
+- Discussions remain focused and actionable
+- Feedback is easier to incorporate early in the process
+
+If you're working on a large feature, consider:
+- Breaking it into multiple PRs
+- Creating a draft PR to show the overall design
+- Discussing the approach in a GitHub issue first
+
+### Merging PRs
+
+- PRs are merged using **squash and merge**
+- At least one committer approval is required
+- For significant changes, two committer approvals may be required
+- Committers will ensure at least 24 hours pass for major changes to allow
community review
+
+## Code Style and Formatting
+
+Auron enforces consistent code style across Java, Scala, and Rust code.
+
+### Automatic Formatting
+
+Use the `dev/reformat` script to format all code:
+
+```bash
+# Format all code
+./dev/reformat
+
+# Check formatting without making changes
+./dev/reformat --check
+```
+
+### License Headers
+
+All source files must include the Apache License 2.0 header. The build will
fail if headers are missing or incorrect.
+
+## Testing
+
+### Unit Tests
+
+- **Java/Scala tests**: Use ScalaTest framework
+- **Rust tests**: Use standard Rust test framework
+
+```bash
+# Run Scala tests
+./build/mvn test -Pspark-3.5 -Pscala-2.12
+
+# Run Rust tests
+cargo test
+```
+
+### Test Coverage
+
+When adding new features or fixing bugs:
+
+1. Add unit tests to cover the new code paths
+2. If the feature is not covered by existing Spark tests, add integration tests
+3. Ensure all tests pass before submitting your PR
+
+## Documentation
+
+### When to Update Documentation
+
+Update documentation when your changes:
+
+- Add new features or APIs
+- Change existing behavior
+- Add new configuration options
+- Affect how users build or deploy Auron
+
+### Documentation Locations
+
+- **README.md**: High-level project overview and quick start
+- **Code comments**: Inline documentation for complex logic
+- **Configuration**: Update if adding new config properties
+
+## Communication
+
+### Mailing Lists
+
+The primary communication channel for the Apache Auron community:
+
+- **[email protected]**: Development discussions
+ - Subscribe:
[[email protected]](mailto:[email protected])
+ - Unsubscribe:
[[email protected]](mailto:[email protected])
+
+### GitHub Issues
+
+- Search existing issues before creating a new one
+- Provide clear reproduction steps for bugs
+- Include environment details (Spark version, Scala version, OS, etc.)
+- Use issue templates when available
+
+### GitHub Discussions
+
+Use GitHub Discussions for:
+- Questions about using Auron
+- Feature proposals and design discussions
+- General community discussions
+
+## License
+
+By contributing to Apache Auron, you agree that your contributions will be
licensed under the [Apache License 2.0](LICENSE).
+Thank you for contributing to Apache Auron! Your efforts help make this
project better for everyone. 🚀
diff --git a/README.md b/README.md
index 7001eb6f..46924389 100644
--- a/README.md
+++ b/README.md
@@ -119,9 +119,9 @@ Contact us through the following mailing list.
| [[email protected]](mailto:[email protected]) | Development-related
discussions | [Subscribe](mailto:[email protected]) |
[Unsubscribe](mailto:[email protected]) |
-### Report Issues or Submit Pull Request
+### Contributing
-If you meet any questions, connect us and fix it by submitting a 🔗[Pull
Request](https://github.com/apache/auron/pulls).
+Interested in contributing to Auron? Please read our [Contributing
Guide](CONTRIBUTING.md) for detailed information on how to get started.
## License
