This is an automated email from the ASF dual-hosted git repository.
dongjoon pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/orc.git
The following commit(s) were added to refs/heads/main by this push:
new 3ebeed865 ORC-2143: Add `AGENTS.md` for AI coding assistants
3ebeed865 is described below
commit 3ebeed865fa7e4bac59e0bf6f8cb6c71236170f6
Author: Dongjoon Hyun <[email protected]>
AuthorDate: Mon Mar 23 14:48:09 2026 -0700
ORC-2143: Add `AGENTS.md` for AI coding assistants
### What changes were proposed in this pull request?
This PR introduces an `AGENTS.md` file at the root of the repository.
`AGENTS.md` is a dedicated documentation file intended to guide AI coding
assistants (such as GitHub Copilot, Cursor, Gemini, etc.) when they are used by
contributors.
It provides AI agents with essential project context, including:
- The separation of C++ (`c++/`) and Java (`java/`) modules
- Accurate build and testing commands (CMake / Maven wrap)
- Issue tracking conventions (requiring JIRA `ORC-XXXX`,
`dev/create_orc_jira.py`)
- Recommended local multi-environment testing strategy [docker/run-all.sh]
and personal fork GitHub Actions tests.
### Why are the changes needed?
As more developers use AI-assisted tools for coding, these tools often lack
repository-specific context, leading to incorrect assumptions (e.g., suggesting
raw `mvn` instead of `./mvnw`, or standard CMake instead of `make test-out`).
This guideline will significantly improve the quality, accuracy, and compliance
of the code and commands generated by AI agents for both new and existing
contributors.
### How was this patch tested?
Manual review.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: `Gemini 3.1 Pro (High)` on `Antigravity`.
Closes #2593 from dongjoon-hyun/ORC-2143.
Authored-by: Dongjoon Hyun <[email protected]>
Signed-off-by: Dongjoon Hyun <[email protected]>
---
AGENTS.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 62 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..b3985c1b7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,62 @@
+# AI Agent Guidelines for Apache ORC
+
+Welcome! If you are an AI coding assistant (like GitHub Copilot, Cursor, or
Gemini) working on this repository, please adhere to the following guidelines.
+
+## 1. Project Structure
+Apache ORC includes both Java and C++ libraries that are completely
independent of each other.
+- `c++/` - the C++ reader and writer
+- `java/` - the Java reader and writer
+- `docker/` - docker scripts to build and test on various linuxes
+- `examples/` - various ORC example files that are used to test compatibility
+- `cmake_modules/` - CMake modules
+- `tools/` - C++ tools for reading and inspecting ORC files
+- `site/` - the website and documentation
+
+## 2. Build Instructions
+### Java
+The Java project is built using Maven wrapper. Use Java 17 or higher.
+```bash
+cd java
+./mvnw package -DskipTests
+```
+
+### C++
+The C++ project uses CMake. Use CMake 3.25.0+.
+```bash
+mkdir build && cd build
+cmake ..
+make package
+```
+*Note: To build with Meson, refer to the README.md.*
+
+## 3. Testing
+Before submitting changes, ensure you run the appropriate test suites.
+
+### Testing Java
+```bash
+cd java
+./mvnw test
+```
+
+### Testing C++
+```bash
+cd build
+make test-out
+```
+
+## 4. Code Style & Linting
+- Always keep the scope of your changes minimal.
+- Do not make formatting changes that are unrelated to the current task.
+- Follow the existing style of the file you are modifying (e.g., C++
formatting using `clang-format`, Java formatting rules).
+
+## 5. Submitting Changes & Bug Tracking
+- **Jira**: Apache ORC uses Jira for issue tracking
(https://orc.apache.org/bugs).
+- **Commit Messages**: Reference the Jira ticket in the commit message if
applicable (e.g., `ORC-XXXX: Fix issue...`). There is a helper script
`dev/create_orc_jira.py`.
+- **Pull Requests**: Explain the reasoning behind your changes clearly. To
ensure your changes are correct before submitting a PR to `apache/orc`, you can:
+ 1. Run the tests locally (`mvn test` or `make test`).
+ 2. Use the Docker scripts in `docker/` (e.g., `cd docker && ./run-all.sh
local main`).
+ 3. **Trigger GitHub Actions**: Push your branch to your personal fork of the
repository and open a Pull Request there. This will automatically run
`.github/workflows/build_and_test.yml` on your own GitHub account's compute
before you submit it to the upstream ASF repository.
+
+## 6. General Advice
+- **Do not introduce breaking changes** to the ORC file format serialization
unless explicitly requested and discussed.
+- Ensure cross-compatibility between C++ and Java implementations if you are
making logic or behavioral changes to readers / writers.
