diff --git a/CLAUDE.md b/CLAUDE.md index 9a157d97c..f70992165 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 +``` + +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. + ## 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