Skip to content

Commit 2a61bdd

Browse files
zjw1111zjw1111
authored
docs: add coding agent guidelines (#410)
1 parent 53f8315 commit 2a61bdd

4 files changed

Lines changed: 148 additions & 1 deletion

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- Please specify the module before the PR name: feat: ... or fix: ... -->
1+
<!-- PR titles must follow Conventional Commits: <type>(<optional-scope>): <description> -->
22

33
### Purpose
44

‎AGENTS.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
<!---
2+
Copyright 2026-present Alibaba Inc.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
-->
16+
17+
# AGENTS.md
18+
19+
This file provides repository-specific instructions for coding agents working on Paimon C++.
20+
For contributor-facing setup and the complete coding conventions, also read [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`docs/code-style.md`](docs/code-style.md).
21+
22+
## Scope
23+
24+
These instructions apply to the entire repository. More deeply nested `AGENTS.md` files, if added later, may provide additional or more specific instructions for their directory trees.
25+
26+
Keep the requested scope exact. Do not include unrelated refactors, formatting changes, API redesigns, dependency updates, or generated files in a focused change.
27+
28+
## Repository Layout
29+
30+
- `include/paimon/`: public C++ API headers.
31+
- `src/paimon/`: core implementation and most unit tests.
32+
- `test/inte/`: end-to-end integration tests.
33+
- `benchmark/`: benchmarks and benchmark-specific tests.
34+
- `examples/`: example programs.
35+
- `docs/` and `apidoc/`: user documentation and API documentation.
36+
- `cmake_modules/` and `build_support/`: CMake helpers and build infrastructure.
37+
- `ci/`: scripts used by continuous integration.
38+
- `test/test_data/`: checked-in test fixtures.
39+
- `third_party/`: third-party sources and patches.
40+
- `build/`, `build-release/`, and `output/`: generated or local build output.
41+
42+
Do not edit `third_party/`, checked-in fixtures, generated output, or Git LFS objects unless the task explicitly requires it. Never add files from local build directories to a change.
43+
44+
## Working Rules
45+
46+
1. Inspect the current implementation, nearby tests, and relevant CMake target before editing.
47+
2. Search for an existing helper or established pattern before adding a new abstraction.
48+
3. Preserve user changes and untracked local files. Do not discard, overwrite, or reformat unrelated work.
49+
4. Prefer the smallest change that fully implements or fixes the requested behavior.
50+
5. Add or update a focused regression test for behavior changes when practical.
51+
6. Do not claim a build or test passed unless the corresponding command completed successfully.
52+
7. Do not commit, push, amend commits, or create a pull request unless explicitly requested.
53+
54+
When changing a public API, check the declaration under `include/paimon/`, its implementation, symbol visibility, documentation, callers, and tests together.
55+
56+
## C++ Requirements
57+
58+
The full rules are in [`docs/code-style.md`](docs/code-style.md). In particular:
59+
60+
- Use C++17; do not introduce C++20 or later features.
61+
- Use `Status` and `Result<T>` for fallible operations. Do not use exceptions for production error propagation.
62+
- Propagate errors with the project macros, including `PAIMON_RETURN_NOT_OK` and `PAIMON_ASSIGN_OR_RAISE`.
63+
- Use an explicit type, not `auto`, as the declaration in `PAIMON_ASSIGN_OR_RAISE` and `PAIMON_ASSIGN_OR_RAISE_FROM_ARROW`.
64+
- Prefer `std::unique_ptr` for sole ownership and use `std::shared_ptr` only for genuine shared ownership.
65+
- Use `static Create()` plus a private constructor when object initialization can fail.
66+
- Mark new public API symbols with `PAIMON_EXPORT`.
67+
- Reuse helpers under `src/paimon/common/utils/` instead of duplicating utility code.
68+
- Follow `.clang-format`; do not manually restyle unrelated code.
69+
- Add the repository's Apache 2.0 license header to every new source or documentation file.
70+
71+
## Build and Test
72+
73+
Use an existing configured build directory when it is compatible with the change. To configure a new debug build with tests:
74+
75+
```bash
76+
cmake -S . -B build \
77+
-DCMAKE_BUILD_TYPE=Debug \
78+
-DPAIMON_BUILD_TESTS=ON
79+
```
80+
81+
Start with the narrowest relevant validation:
82+
83+
```bash
84+
cmake --build build --target <test-target> -j "$(nproc)"
85+
./build/debug/<test-binary> --gtest_filter='<Suite.Test>'
86+
```
87+
88+
Then broaden validation in proportion to the change:
89+
90+
```bash
91+
# All unit tests
92+
cmake --build build --target unittest -j "$(nproc)"
93+
94+
# Formatting, lint, and repository checks for changed files
95+
pre-commit run --files <changed-files>
96+
git diff --check
97+
```
98+
99+
For changes to build configuration, public APIs, shared infrastructure, or cross-module behavior, run the relevant wider test suite. The CI-equivalent build entry point is `ci/scripts/build_paimon.sh`; it may rebuild all dependencies and take substantially longer than a focused local target.
100+
101+
If a required check cannot be run because of missing dependencies, unsupported hardware, or time constraints, report exactly what was and was not run.
102+
103+
## Testing Conventions
104+
105+
- Use GoogleTest and name test files `*_test.cpp`.
106+
- Place unit tests next to the corresponding implementation unless an existing target establishes another location.
107+
- Extend an existing test target when appropriate instead of creating a new executable for one small test.
108+
- Test externally observable behavior and failure cases; avoid coupling tests to incidental implementation details.
109+
- Use existing test utilities and temporary-directory helpers. Do not write tests that depend on developer-specific absolute paths.
110+
- Keep fixtures deterministic and small. Do not rewrite existing fixture data unless the task explicitly calls for it.
111+
- Use `ASSERT_*` when later assertions depend on the condition succeeding.
112+
113+
## Delivery
114+
115+
Before handing off a change:
116+
117+
1. Review `git diff` for accidental or unrelated edits.
118+
2. Run `git diff --check`.
119+
3. Run the narrowest relevant build and test, plus any wider checks justified by the risk.
120+
4. Summarize the changed behavior and list the exact validation commands that ran.
121+
5. Call out skipped validation, remaining risks, or follow-up work explicitly.
122+
6. When explicitly asked to commit, follow the Conventional Commits requirements in [`CONTRIBUTING.md`](CONTRIBUTING.md#commit-messages-and-pull-request-titles).
123+
7. When explicitly asked to open a pull request, follow [`CONTRIBUTING.md`](CONTRIBUTING.md#commit-messages-and-pull-request-titles), use a Conventional Commits title, and complete every applicable section of [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md).

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎CONTRIBUTING.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,27 @@ If you find a bug or want to request a feature, please open an [issue](https://g
2626

2727
---
2828

29+
## Commit Messages and Pull Request Titles
30+
31+
Use the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages and pull request titles:
32+
33+
```text
34+
<type>(<optional-scope>): <description>
35+
```
36+
37+
Examples:
38+
39+
```text
40+
feat(parquet): support page-level bitmap filtering
41+
fix: handle non-contiguous row ranges
42+
test(executor): add shutdown coverage
43+
docs: update the build instructions
44+
```
45+
46+
Choose a type and optional scope that accurately describe the change. Keep the description concise and write it in the imperative mood. A pull request title should summarize the complete change and use the same format.
47+
48+
---
49+
2950
## Submitting Pull Requests
3051

3152
1. **Fork** the repository and create a feature branch from `main`.
@@ -34,6 +55,8 @@ If you find a bug or want to request a feature, please open an [issue](https://g
3455
4. Ensure all checks pass.
3556
5. Open a pull request against `main`. Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
3657

58+
When addressing review feedback or adding follow-up changes to an open pull request, prefer a separate commit instead of amending and force-pushing existing commits. This makes the incremental diff easier for reviewers to inspect. Rewrite existing commits only when a maintainer explicitly requests it.
59+
3760
### PR Checklist
3861

3962
Before submitting, please verify:

0 commit comments

Comments
 (0)