diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 1320da73b..50d87f7f8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,4 +1,4 @@ - + ### Purpose diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..f70d3e3b3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,123 @@ + + +# AGENTS.md + +This file provides repository-specific instructions for coding agents working on Paimon C++. +For contributor-facing setup and the complete coding conventions, also read [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`docs/code-style.md`](docs/code-style.md). + +## Scope + +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. + +Keep the requested scope exact. Do not include unrelated refactors, formatting changes, API redesigns, dependency updates, or generated files in a focused change. + +## Repository Layout + +- `include/paimon/`: public C++ API headers. +- `src/paimon/`: core implementation and most unit tests. +- `test/inte/`: end-to-end integration tests. +- `benchmark/`: benchmarks and benchmark-specific tests. +- `examples/`: example programs. +- `docs/` and `apidoc/`: user documentation and API documentation. +- `cmake_modules/` and `build_support/`: CMake helpers and build infrastructure. +- `ci/`: scripts used by continuous integration. +- `test/test_data/`: checked-in test fixtures. +- `third_party/`: third-party sources and patches. +- `build/`, `build-release/`, and `output/`: generated or local build output. + +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. + +## Working Rules + +1. Inspect the current implementation, nearby tests, and relevant CMake target before editing. +2. Search for an existing helper or established pattern before adding a new abstraction. +3. Preserve user changes and untracked local files. Do not discard, overwrite, or reformat unrelated work. +4. Prefer the smallest change that fully implements or fixes the requested behavior. +5. Add or update a focused regression test for behavior changes when practical. +6. Do not claim a build or test passed unless the corresponding command completed successfully. +7. Do not commit, push, amend commits, or create a pull request unless explicitly requested. + +When changing a public API, check the declaration under `include/paimon/`, its implementation, symbol visibility, documentation, callers, and tests together. + +## C++ Requirements + +The full rules are in [`docs/code-style.md`](docs/code-style.md). In particular: + +- Use C++17; do not introduce C++20 or later features. +- Use `Status` and `Result` for fallible operations. Do not use exceptions for production error propagation. +- Propagate errors with the project macros, including `PAIMON_RETURN_NOT_OK` and `PAIMON_ASSIGN_OR_RAISE`. +- Use an explicit type, not `auto`, as the declaration in `PAIMON_ASSIGN_OR_RAISE` and `PAIMON_ASSIGN_OR_RAISE_FROM_ARROW`. +- Prefer `std::unique_ptr` for sole ownership and use `std::shared_ptr` only for genuine shared ownership. +- Use `static Create()` plus a private constructor when object initialization can fail. +- Mark new public API symbols with `PAIMON_EXPORT`. +- Reuse helpers under `src/paimon/common/utils/` instead of duplicating utility code. +- Follow `.clang-format`; do not manually restyle unrelated code. +- Add the repository's Apache 2.0 license header to every new source or documentation file. + +## Build and Test + +Use an existing configured build directory when it is compatible with the change. To configure a new debug build with tests: + +```bash +cmake -S . -B build \ + -DCMAKE_BUILD_TYPE=Debug \ + -DPAIMON_BUILD_TESTS=ON +``` + +Start with the narrowest relevant validation: + +```bash +cmake --build build --target -j "$(nproc)" +./build/debug/ --gtest_filter='' +``` + +Then broaden validation in proportion to the change: + +```bash +# All unit tests +cmake --build build --target unittest -j "$(nproc)" + +# Formatting, lint, and repository checks for changed files +pre-commit run --files +git diff --check +``` + +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. + +If a required check cannot be run because of missing dependencies, unsupported hardware, or time constraints, report exactly what was and was not run. + +## Testing Conventions + +- Use GoogleTest and name test files `*_test.cpp`. +- Place unit tests next to the corresponding implementation unless an existing target establishes another location. +- Extend an existing test target when appropriate instead of creating a new executable for one small test. +- Test externally observable behavior and failure cases; avoid coupling tests to incidental implementation details. +- Use existing test utilities and temporary-directory helpers. Do not write tests that depend on developer-specific absolute paths. +- Keep fixtures deterministic and small. Do not rewrite existing fixture data unless the task explicitly calls for it. +- Use `ASSERT_*` when later assertions depend on the condition succeeding. + +## Delivery + +Before handing off a change: + +1. Review `git diff` for accidental or unrelated edits. +2. Run `git diff --check`. +3. Run the narrowest relevant build and test, plus any wider checks justified by the risk. +4. Summarize the changed behavior and list the exact validation commands that ran. +5. Call out skipped validation, remaining risks, or follow-up work explicitly. +6. When explicitly asked to commit, follow the Conventional Commits requirements in [`CONTRIBUTING.md`](CONTRIBUTING.md#commit-messages-and-pull-request-titles). +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). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 45f584e5d..504a70f3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,27 @@ If you find a bug or want to request a feature, please open an [issue](https://g --- +## Commit Messages and Pull Request Titles + +Use the [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages and pull request titles: + +```text +(): +``` + +Examples: + +```text +feat(parquet): support page-level bitmap filtering +fix: handle non-contiguous row ranges +test(executor): add shutdown coverage +docs: update the build instructions +``` + +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. + +--- + ## Submitting Pull Requests 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 4. Ensure all checks pass. 5. Open a pull request against `main`. Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md). +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. + ### PR Checklist Before submitting, please verify: