From 43e04a205f55db083359e9908149fb170508d2f9 Mon Sep 17 00:00:00 2001 From: ColinLee Date: Mon, 16 Nov 2026 10:35:01 +0800 Subject: [PATCH 1/2] docs: clarify local test binaries vs pre-push Maven verification Directly built test binaries are the fast iteration path, but CI builds and tests through Maven, so they miss Maven's compile/link/package steps (e.g. a missing out-of-class constexpr definition links on macOS but fails under Linux/LTO). Document both entry points and require the Maven profile verification before committing or pushing. --- CLAUDE.md | 24 ++++++++++++++++++++++++ cpp/CLAUDE.md | 6 +++++- python/CLAUDE.md | 5 ++++- 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9a157d97c..49f0c5cac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,30 @@ The root `pom.xml` orchestrates all three via Maven profiles: ./mvnw clean verify -P with-python # Python (requires C++ built first) ``` +### Local Iteration vs. Pre-Push Verification + +These two entry points serve different purposes and are not interchangeable. + +**While iterating**, run the already-built test artifacts directly for fast feedback: + +```bash +./cpp/build/Release/lib/TsFile_Test # C++ test binary +./cpp/build/Release/lib/TsFile_Test --gtest_filter=Foo.* # narrow to relevant cases +cd python && pytest tests/ # Python tests +``` + +**Before committing or pushing**, run the Maven entry point that CI uses, from the repository root: + +```bash +./mvnw -P with-cpp verify # C++ changes +./mvnw -P with-python verify # Python changes (also builds C++) +./mvnw -P with-java verify # Java changes +``` + +Omit `clean` for these runs: it discards cached dependency downloads and rebuilds them. The full-suite command under [Required Checks Before Pushing](#required-checks-before-pushing) still applies when pushing code. + +CI compiles, links, and packages through Maven, so running the test binary alone does not reproduce that pipeline. For example, a `constexpr` constant without an out-of-class definition links fine on macOS with the directly built binary but fails under Linux/LTO in CI. + ## Cross-Module Dependencies - **Python depends on C++**: The Python module uses Cython to bind to the C++ shared library (`libtsfile`). C++ must be built before Python (`-P with-python` implies C++ build). diff --git a/cpp/CLAUDE.md b/cpp/CLAUDE.md index 32d045e22..ca9e33b72 100644 --- a/cpp/CLAUDE.md +++ b/cpp/CLAUDE.md @@ -51,11 +51,15 @@ make -j$(nproc) # Via Maven from repo root ./mvnw clean verify -P with-cpp -# Run all tests +# Run all tests (fast iteration only: runs the built binary and skips the +# Maven compile/link/package steps that CI performs) ./build/Release/lib/TsFile_Test # Run specific test suite ./build/Release/lib/TsFile_Test --gtest_filter=SnappyCompressorTest.* + +# Before pushing, use the Maven entry point CI uses (from repo root, no clean) +./mvnw -P with-cpp verify ``` ## Build Options (CMake) diff --git a/python/CLAUDE.md b/python/CLAUDE.md index 60c609313..f0a2650ff 100644 --- a/python/CLAUDE.md +++ b/python/CLAUDE.md @@ -42,12 +42,15 @@ The Python module depends on the C++ shared library (`libtsfile`). **Build C++ f cd python python setup.py build_ext --inplace -# Run tests +# Run tests (fast iteration against the in-place build) pytest tests/ # Run a single test pytest tests/test_write_and_read.py -k "test_name" +# Before pushing, use the Maven entry point CI uses (from the repo root, no clean) +./mvnw -P with-python verify + # ASan/LSan coverage of the bindings (Linux; run from the repo root; see # SANITIZER.md). TSFILE_SANITIZER is required or test_sanitizer_ownership.py # skips every case, and the runtime must be preloaded or the instrumented From 96adee03d8699e1bac12a0da1cf2dfab6916f567 Mon Sep 17 00:00:00 2001 From: ColinLee Date: Mon, 16 Nov 2026 10:35:58 +0800 Subject: [PATCH 2/2] docs: do not contradict the required pre-push checks The Required Checks section already mandates the clean full Maven suite; describe the profile commands as smoke checks instead of telling readers to omit clean. --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 49f0c5cac..f70992165 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -65,7 +65,7 @@ cd python && pytest tests/ # Python tests ./mvnw -P with-java verify # Java changes ``` -Omit `clean` for these runs: it discards cached dependency downloads and rebuilds them. The full-suite command under [Required Checks Before Pushing](#required-checks-before-pushing) still applies when pushing code. +These are smoke checks for a branch in flight. The full pre-push requirements — including the `clean` full-suite build, the C++ ASan run, Python binding sanitizer coverage and `spotless:check` — are defined under [Required Checks Before Pushing](#required-checks-before-pushing) and are not replaced by the commands above. CI compiles, links, and packages through Maven, so running the test binary alone does not reproduce that pipeline. For example, a `constexpr` constant without an out-of-class definition links fine on macOS with the directly built binary but fails under Linux/LTO in CI.