This is an automated email from the ASF dual-hosted git repository. jmclean pushed a commit to branch contributing in repository https://gitbox.apache.org/repos/asf/gravitino.git
commit d7201d37bbec497db42d2147cc2f11b23f93162e Author: Justin Mclean <[email protected]> AuthorDate: Thu Aug 7 15:18:33 2025 +1000 improved contributing --- CONTRIBUTING.md | 342 ++++++++++++++++++++++++++------------------------------ 1 file changed, 158 insertions(+), 184 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ce11c9490d..3b0e09c0d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,272 +19,246 @@ # Contributing to Apache Gravitino -Thank you for your interest in contributing to Apache Gravitino! Your support is invaluable in enhancing the project, and we warmly welcome contributions of all kinds. Gravitino appreciates your assistance in making it better, whether through code contributions, documentation, tests, best practices, graphic design, or any other means that have a positive impact. - -To ensure a smooth and productive collaboration, please take a moment to review and follow our contribution guidelines before getting started. - -## Table of contents - -- [Getting Started](#getting-started) - - [Fork the Repository](#fork-the-repository) - - [Development Setup](#development-setup) - - [Using IntelliJ (Optional)](#using-intellij-optional) - - [Using VS Code (Optional)](#using-vs-code-optional) - - [Handling Memory Issues in WSL](#handling-memory-issues-in-wsl) -- [Project Overview and Policies](#project-overview-and-policies) - - [Project Overview](#project-overview) - - [Management Policies](#management-policies) - - [Future Development Directions](#future-development-directions) -- [Contribution Guidelines](#contribution-guidelines) - - [Code of Conduct](#code-of-conduct) - - [Reporting Bugs](#reporting-bugs) - - [Suggesting Enhancements](#suggesting-enhancements) - - [Good First Issues](#good-first-issues) - - [Working on Issues](#working-on-issues) - - [Creating Pull Requests](#creating-pull-requests) - - [The Review Process](#the-review-process) -- [Testing](#testing) -- [Coding Standards](#coding-standards) -- [Community and Communication](#community-and-communication) -- [License](#license) - -## Getting started - -### Fork the repository - -Either click the "Fork" button at the top right of the repository's page on GitHub OR create a fork on your local machine using `git clone`. +Welcome! This guide will help you get started contributing to Apache Gravitino, whether you're filing an issue, improving documentation, or submitting code. -```bash -git clone https://github.com/apache/gravitino.git -cd gravitino -``` - -### Development Setup +Gravitino welcomes all kinds of contributionsβincluding code (Java, Python), documentation, testing, design, and feedback. Your involvement helps strengthen the project. -Once you have cloned the [GitHub repository](https://github.com/apache/gravitino), see [how to build](/docs/how-to-build.md) for instructions on how to build, or you can use the provided docker images at [Apache DockerHub repository](https://hub.docker.com/u/apache). +Apache Gravitino is a metadata and data lake federation layer for AI and analytics. It graduated from the Apache Software Foundation's Incubator in June 2025 and is now a top level project maintained by a growing community. -To stop and start a local Gravitino server via `bin/gravitino.sh start` and `bin/gravitino.sh stop` in a Gravitino distribution, see [how to build](/docs/how-to-build.md) for more instructions. +Gravitino follows ASF-wide contribution and governance practices. Project-specific workflows are explained where they differ. -### Using IntelliJ (Optional) +Please review the following guidelines for a smooth contribution process. -**On Windows:** +## π Table of Contents -1. Open the Gravitino project that was just downloaded. +* [π Project Overview and Policies](#-project-overview-and-policies) +* [π¬ Community and Communication](#-community-and-communication) +* [π Code of Conduct](#-code-of-conduct) +* [π¬ How Decisions Are Made](#-how-decisions-are-made) +* [π± Growing Your Involvement](#-growing-your-involvement) +* [π§ͺ Continuous Integration](#-continuous-integration) +* [π Need Help?](#-need-help) +* [π Getting Started](#-getting-started) +* [ποΈ Quick Start for First-Time Contributors](#-quick-start-for-first-time-contributors) +* [π Making Contributions](#-making-contributions) +* [π Contributing to Design and Documentation](#-contributing-to-design-and-documentation) +* [π Reviewing and Triaging Contributions](#-reviewing-and-triaging-contributions) +* [π Creating Pull Requests](#-creating-pull-requests) +* [π» Setting Up Development Environment](#-setting-up-development-environment) +* [π§° Setting Up Your IDE (Optional)](#-setting-up-your-ide-optional) +* [π‘ Tips for WSL Users](#-tips-for-wsl-users) +* [βοΈ Build Profiles and JDK Requirements](#-build-profiles-and-jdk-requirements) +* [π¨ Formatting Code with Spotless](#-formatting-code-with-spotless) +* [ποΈ File Structure Overview](#-file-structure-overview) +* [π§ͺ Writing and Running Tests](#-writing-and-running-tests) +* [𧱠Following Coding Standards](#-following-coding-standards) +* [π Managing Dependencies](#-managing-dependencies) +* [π‘οΈ Performing Compliance and Legal Checks](#-performing-compliance-and-legal-checks) +* [π License](#-license) +* [π Reporting Security Issues](#-reporting-security-issues) +* [π Acknowledging Contributors](#-acknowledging-contributors) +* [π Glossary](#-glossary) -2. Go to `File > Project Structure > Project` and change to the SDK you downloaded in WSL. +## π Project Overview and Policies -3. If the SDK does not appear, manually add the SDK. +* **Overview**: See the [Gravitino website](https://gravitino.apache.org) and [README.md](README.md). +* **Governance**: See [GOVERNANCE.md](GOVERNANCE.md). +* **Roadmap**: See [ROADMAP.md](ROADMAP.md). -4. To find the SDK location, run this command in WSL: +Apache Gravitino is a [Top-Level Project of the ASF](https://www.apache.org/foundation/). - **On Ubuntu (WSL):** - ```sh - which java - ``` +## π¬ Community and Communication -IntelliJ IDEA is an integrated development environment (IDE) for Java development. Setting the project SDK ensures that IntelliJ uses the correct Java version to build and run the project. +Gravitino is a collaborative project. We encourage open communication and transparent decision-making. You can: -You can open up WSL in the IntelliJ terminal. Find the down arrow and select ubuntu. +* Subscribe to the developer mailing list: `[email protected]` + * [View archives](https://lists.apache.org/[email protected]) +* Discuss issues via [GitHub Issues](https://github.com/apache/gravitino/issues) +* Join discussions via ASF Slack (invite link: [https://s.apache.org/slack-invite](https://s.apache.org/slack-invite)) -### Using VS Code (Optional) +Please follow the [ASF Code of Conduct](https://www.apache.org/foundation/policies/conduct.html) in all interactions. -#### Set up WSL Extension in VSCode +## π Code of Conduct -**On Windows:** +We are committed to fostering a welcoming and inclusive community. Please review and adhere to our [Code of Conduct](https://github.com/apache/gravitino/blob/main/CODE_OF_CONDUCT.md) in all project spaces. -1. Open VSCode extension marketplace, search for and install **WSL**. +## π¬ How Decisions Are Made -2. Press `Ctrl+Shift+P` to open the command palette, and run `Shell Command: Install 'code' command in PATH`. +Gravitino uses [Apacheβs consensus-based decision-making](https://www.apache.org/foundation/glossary.html#ConsensusApproval). Most decisions happen on the `dev@` mailing list or via GitHub PR discussions. -Installing the WSL extension in VSCode allows you to open and edit files in your WSL environment directly from VSCode. Adding the `code` command to your PATH lets you open VSCode from the WSL terminal. +## π± Growing Your Involvement -#### Verify and Configure Environment Variables +Contributors who participate actively and constructively may be invited to become committers or join the PMC. Merit is earned through consistent contributions and community engagement. -**On Windows:** +## π§ͺ Continuous Integration -1. Add VSCode path to the environment variables. The default installation path for VSCode is usually: +All PRs are automatically tested using GitHub Actions. Please check test results and fix failures before requesting a review. - ```plaintext - C:\Users\<Your-Username>\AppData\Local\Programs\Microsoft VS Code\bin - ``` +## π Need Help? - Replace `<Your-Username>` with your actual Windows username. +If you're stuck, ask on the `dev@` mailing list or open a GitHub Discussion. We're here to help. - Example: +## π Getting Started - ```plaintext - C:\Users\epic\AppData\Local\Programs\Microsoft VS Code\bin - ``` +### Fork the Repository -Adding VSCode to the environment variables ensures you can open VSCode from any command prompt or terminal window. +Click the "Fork" button on GitHub or use: -**On Ubuntu (WSL):** - -```sh -code --version +```bash +git clone https://github.com/apache/gravitino.git cd gravitino -code . ``` -Running `code --version` verifies that the `code` command is available. Using `code .` opens the current directory in VSCode. - -#### Open a WSL Project in Windows VSCode - -**On Ubuntu (WSL):** - -1. **Navigate to Your Project Directory** - - Use the terminal to navigate to the directory of your project. For example: - - ```sh - cd gravitino - ``` - -2. **Open the Project in VSCode** - - In the WSL terminal, type the following command to open the current directory in VSCode: - - ```sh - code . - ``` - - This command will open the current WSL directory in VSCode. If you haven't added `code` to your path, follow these steps: - -- Open VSCode on Windows. - -- Press `Ctrl+Shift+P` to open the command palette. - -- Type and select `Shell Command: Install 'code' command in PATH`. +Check out the [ASF New Contributor Guide](https://www.apache.org/dev/new-committers-guide.html) for an overview of how ASF projects work. -3. **Ensure Remote - WSL is Active** +## ποΈ Quick Start for First-Time Contributors - When VSCode opens, you should see a green bottom-left corner indicating that VSCode is connected to WSL. If not, click on the green area and select `Remote-WSL: New Window` or `Remote-WSL: Reopen Folder in WSL`. +1. Fork and clone the repository +2. Build the project using [how to build](/docs/how-to-build.md) +3. Pick an issue or start a discussion +4. Submit a pull request and collaborate with reviewers -4. **Edit and Develop Your Project** +## π Making Contributions - You can now edit and develop your project files in VSCode as if they were local files. The Remote - WSL extension seamlessly bridges the file system between Windows and WSL. +We welcome all types of contributions: -### Handling Memory Issues in WSL +* **Code** β bug fixes, new features, refactoring, integrations + * If you're adding or updating a connector, catalog, or integration, please discuss it on the dev@ mailing list first. +* **Documentation** β tutorials, guides, references +* **Review** β triage and review issues and PRs +* **Community** β answer questions, join discussions -Here are some solutions if you encounter a memory issue when using WSL. +Look for [good first issues](https://github.com/apache/gravitino/labels/good%20first%20issue) to get started. Discuss plans on GitHub or the dev@ mailing list. Small pull requests are easiest to review. -1. **Shut down WSL** - If your WSL is open, you can shut it down in Windows PowerShell using the following command: +## π Contributing to Design and Documentation - ```powershell - wsl --shutdown - ``` +Design and documentation are essential to Gravitinoβs usability and growth. -2. **Navigate to user folder** +You can contribute by: - Open File Explorer and navigate to `C:\Users\<your-username>`. +* Improving documentation in `docs/` +* Clarifying APIs and references +* Reviewing documents for accuracy +* Submitting mockups or usability suggestions -3. **Create the `.wslconfig` file** +## π Reviewing and Triaging Contributions - Open up Notepad or another text editor and input the following: +Reviewing and triaging helps maintain the project. You can: - ```plaintext - [wsl2] - memory=4GB # Limits VM memory in WSL 2 up to 4GB - processors=4 # Makes the WSL 2 VM use four virtual processors - ``` +* Reproduce bugs and confirm issues +* Add labels to categorize +* Suggest improvements on PRs +* Review code and give feedback - *The memory and processor usage can be changed depending on your system's hardware.* +## π Creating Pull Requests -4. **Save the file** +* Use feature branches +* Write clear commit messages and PR descriptions +* Link to issues (e.g., `Fixes #123`) +* Respond to reviewer feedback - Save the file as `".wslconfig"`. Be sure to include the quotes to let Windows know that this isn't a text file. +## π» Setting Up Development Environment -## Project Overview and Policies +Follow [how to build](/docs/how-to-build.md) or use [Apache DockerHub](https://hub.docker.com/u/apache). Start Gravitino with: -### Project Overview - -For an overview of the project, see [README.md](README.md). - -### Management Policies - -For project management policies, refer to [GOVERNANCE.md](GOVERNANCE.md). - -### Future Development Directions - -Refer to the [ROADMAP.md](ROADMAP.md) document for future development directions. - -## Contribution guidelines +```bash +bin/gravitino.sh start +bin/gravitino.sh stop +``` -### Code of Conduct +You can also build manually with: -Please read and follow the [Code of Conduct](CODE_OF_CONDUCT.md). Gravitino provides a welcoming and inclusive environment for all contributors. +```bash +./mvnw clean install +``` -### Reporting bugs +## π§° Setting Up Your IDE (Optional) -If you find a bug in Gravitino, please open an issue on GitHub. Include as much detail as possible, such as a clear description, reproduction steps, and your environment. Please follow the template provided. If you encounter a security issue, please refer to [SECURITY.md](SECURITY.md). +Import Gravitino into IntelliJ IDEA or Eclipse as a Gradle project. -### Suggesting enhancements +## π‘ Tips for WSL Users -If you have ideas for enhancements or new features, feel free to create an issue to discuss them. Gravitino welcomes suggestions and provides prompt feedback on their feasibility and relevance. +If using WSL on Windows, install Java and dev tools inside WSL. Access files via `/mnt/c/...` paths. -### Good First Issues +## βοΈ Build Profiles and JDK Requirements -If you are new to open source or can't find something to work on, check out the [Good First Issues list](https://github.com/apache/gravitino/contribute). +Gravitino uses Maven profiles for Scala: -### Working on Issues +* `-Pscala-2.12` for Scala 2.12 +* `-Pscala-2.13` for Scala 2.13 (default) -Check out the list of open issues and find one that interests you. You can also comment on an issue to indicate that you're working on it. Please keep the issue updated with your progress. +Gravitino supports JDK 8, 11 and 17. -## Creating Pull Requests +## π¨ Formatting Code with Spotless -Create a new branch from `main` for your changes: +We use [Spotless](https://github.com/diffplug/spotless) for code formatting. Run: ```bash -git checkout -b your-branch-name +./gradlew spotlessApply ``` -Make your changes and commit them. Be sure to write clear and concise commit messages. +## ποΈ File Structure Overview -```bash -git commit -m "Your commit message" -``` +Key directories in the Gravitino repo: -Push your changes to your fork on GitHub: +* `api/`, `clients/`, `core/`, `server/` β Main components +* `docs/`, `rfc/` β Documentation and design +* `conf/`, `bin/` β Configs and scripts +* `catalogs/`, `spark-connector/`, `trino-connector/` β Integrations -```bash -git push your-branch-name -``` +## π§ͺ Writing and Running Tests -After you have pushed your changes, create a pull request (PR) in the Gravitino repository. Be sure to provide a detailed description of your changes, reference any related issues, and please follow the template provided. Gravitino's maintainers evaluate pull requests, offer feedback, and assist in merging project changes. +Add or update tests in your PR. Test open PRs locally to help maintainers. -### The Review Process +## π§ Following Coding Standards -For details on the review process, please refer to [MAINTAINERS.md](MAINTAINERS.md). +* Follow Java and Python idioms +* Include useful comments +* Keep methods and classes focused +* Format with Spotless -## Testing +## π¦ Managing Dependencies -The CI infrastructure runs unit and integration tests on each pull request. Please make sure these tests pass before making a pull request. +* Avoid unnecessary dependencies +* Prefer well-maintained libraries +* Discuss major additions on dev@ -The unit tests run on every build, and integration tests run as needed. See [how to test](docs/how-to-test.md) for more information. +## π‘οΈ Performing Compliance and Legal Checks -Add unit tests to provide coverage when adding new code or fixing a bug. +Before contributing: -## Coding standards +* Review [ASF License and IP Guidelines](https://www.apache.org/legal/) +* Ensure all code is original or properly licensed and compatable with the Apache License -Spotless checks code formatting. If your code is correctly formatted, the build succeeds. To format your code correctly, please use Spotless. +## π License -```bash -./gradlew spotlessApply -``` +Contributions are under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0). + +If contributing on behalf of an employer or regularly, you may need to submit an [ICLA](https://www.apache.org/licenses/icla.html). See [ASF Contributor FAQs](https://www.apache.org/dev/new-committers-guide.html#cla). -All files must have a license header, and the build fails if any files are missing license headers. If you are adding third-party code, you may need to add the third-party license to Gravitino's LICENSE and NOTICE files. If you are unsure of how to do this, please ask for help. +Official repo: [https://github.com/apache/gravitino](https://github.com/apache/gravitino) -Please add unit tests to provide code coverage for any bugs or new code. The project may not accept code without unit tests. +## π Reporting Security Issues -All text files should use macOS/unix style line endings (LF), not Windows-style line endings (CRLF). +To report a vulnerability, follow the [SECURITY.md](SECURITY.md) instructions. Responsible disclosure is appreciated and handled per ASF guidelines. -## Community and communication +## π Acknowledging Contributors -Join the [community mailing list](https://lists.apache.org/[email protected]) to discuss ideas and seek help. You are also encouraged to use GitHub discussions. +Contributors are recognized in release notes. All types of contributions are valued. -## License +See the full list of contributors on GitHub: [https://github.com/apache/gravitino/graphs/contributors](https://github.com/apache/gravitino/graphs/contributors) -When contributing to this project, you agree that your contributions use the Apache License version 2. Please ensure you have permission to do this if your employer requires it. +## π Glossary -Thank you for your contributions to Gravitino! The project appreciates your help in making it a success. +* **ASF**: Apache Software Foundation +* **ICLA**: Individual Contributor License Agreement +* **PMC**: Project Management Committee +* **RAT**: Release Audit Tool +* **Spotless**: Code formatter +* **CI**: Continuous Integration +* **PR**: Pull Request +* **WSL**: Windows Subsystem for Linux +* **TLP**: Top-Level Project +* **dev@ list**: Primary development mailing list +* **AI**: Artificial Intelligence +* **IDE**: Integrated Development Environment
