From 55662d06fc36ecfa901f408afffdcfc1e57b4aeb Mon Sep 17 00:00:00 2001
From: Chojan Shang <psiace@apache.org>
Date: Wed, 14 Jan 2026 04:38:16 +0000
Subject: [PATCH 1/2] docs: document build and test workflows

---
 CONTRIBUTING.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d714ddf..6ae7828 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,6 +32,91 @@ cargo version
 
 To keep code style consistent, run `cargo x lint --fix` to automatically fix any style issues before committing your changes.
 
+## Build and Test
+
+We recommend using `cargo x` as a single entrypoint (provided by the workspace `xtask` crate). If you do not have a `cargo x` alias, run the equivalent `cargo run -p x -- ...` command instead.
+
+Build:
+
+```shell
+cargo build --workspace
+```
+
+Test (equivalent to `cargo x test`):
+
+```shell
+cargo run -p x -- test
+# or
+cargo test --workspace --no-default-features
+```
+
+Lint (equivalent to `cargo x lint`):
+
+```shell
+cargo run -p x -- lint
+```
+
+If you want a local `cargo x` alias, add this to `.cargo/config.toml`:
+
+```toml
+[alias]
+x = "run -p x --"
+```
+
+## Manual workflow (without xtask)
+
+`cargo x lint` runs the following steps. Use these directly when you need more control or want to isolate failures:
+
+```shell
+cargo +nightly clippy --tests --all-features --all-targets --workspace -- -D warnings
+cargo +nightly fmt --all --check
+taplo format --check
+typos
+hawkeye check
+```
+
+Automatic fix commands:
+
+```shell
+cargo +nightly clippy --tests --all-features --all-targets --workspace --allow-staged --allow-dirty --fix
+cargo +nightly fmt --all
+taplo format
+hawkeye format --fail-if-updated=false
+```
+
+Install the extra tools with:
+
+```shell
+cargo install taplo-cli typos-cli hawkeye
+```
+
+## Serialization snapshots and test data generation
+
+Some tests depend on snapshot files under `datasketches/tests/serialization_test_data`. If they are missing, tests will fail. Regenerate them with:
+
+```shell
+python3 ./tools/generate_serialization_test_data.py --all
+```
+
+The script pulls `datasketches-java` and `datasketches-cpp` and writes files to:
+
+- `datasketches/tests/serialization_test_data/java_generated_files`
+- `datasketches/tests/serialization_test_data/cpp_generated_files`
+
+You can generate them separately:
+
+```shell
+python3 ./tools/generate_serialization_test_data.py --java
+python3 ./tools/generate_serialization_test_data.py --cpp
+```
+
+The script requires these commands on PATH (and network access):
+
+- Java data: `git`, `java`, `mvn`
+- C++ data: `git`, `cmake`, `ctest`
+
+The current `datasketches-java` generation flow requires JDK >= 25 and Maven >= 3.9.11, otherwise Maven Enforcer will fail.
+
 ## Code of Conduct
 
 We expect all community members to follow our [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html).

From 38421fc5ae3119b42c77607760ff77fb95417e74 Mon Sep 17 00:00:00 2001
From: Chojan Shang <psiace@apache.org>
Date: Wed, 14 Jan 2026 12:41:10 +0000
Subject: [PATCH 2/2] docs: polish x task part

Signed-off-by: Chojan Shang <psiace@apache.org>
---
 CONTRIBUTING.md | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6ae7828..b71cab9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,7 +34,7 @@ To keep code style consistent, run `cargo x lint --fix` to automatically fix any
 
 ## Build and Test
 
-We recommend using `cargo x` as a single entrypoint (provided by the workspace `xtask` crate). If you do not have a `cargo x` alias, run the equivalent `cargo run -p x -- ...` command instead.
+We recommend using `cargo x` as a single entrypoint (provided by the workspace `xtask` crate). This repo defines the `cargo x` alias in `.cargo/config.toml`, which maps to `cargo run --package x -- ...`.
 
 Build:
 
@@ -42,25 +42,18 @@ Build:
 cargo build --workspace
 ```
 
-Test (equivalent to `cargo x test`):
+Test:
 
 ```shell
-cargo run -p x -- test
+cargo x test
 # or
 cargo test --workspace --no-default-features
 ```
 
-Lint (equivalent to `cargo x lint`):
+Lint:
 
 ```shell
-cargo run -p x -- lint
-```
-
-If you want a local `cargo x` alias, add this to `.cargo/config.toml`:
-
-```toml
-[alias]
-x = "run -p x --"
+cargo x lint
 ```
 
 ## Manual workflow (without xtask)