Contributing

Thank you for contributing to Apache DataSketches!

The goal of this document is to provide everything you need to start contributing to this core Rust library.

Your First Contribution

1. Fork the DataSketches repository in your own GitHub account.
2. Create a new Git branch.
3. Make your changes.
4. Submit the branch as a pull request to the upstream repo. A DataSketches team member should comment and/or review your pull request within a few days. Although, depending on the circumstances, it may take longer.

Setup

This repo develops Apache® DataSketches™ Core Rust Library Component. To build this project, you will need to set up Rust development first. We highly recommend using rustup for the setup process.

For Linux or macOS users, use the following command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

For Windows users, download rustup-init.exe from here instead.

Rustup will read the rust-toolchain.toml file and set up everything else automatically. To ensure that everything works correctly, run cargo version under the root directory:

cargo version
# cargo 1.86.0 (<hash> <date>)

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). This repo defines the cargo x alias in .cargo/config.toml, which maps to cargo run --package x -- ....

Build:

cargo build --workspace

Prepare the cross-language serialization test data:

cargo x prepare-testdata

Test:

cargo x test

Lint:

cargo x lint

Public API documentation

• Describe types with noun phrases and API behavior with third-person present-tense verbs such as Creates, Updates, and Returns.
• End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
• Put contract sections and compatibility notes before examples. When applicable, order sections as # Errors, # Panics, and # Examples. Include only sections that describe an actual contract.

Integration test layout

Integration tests for the datasketches crate live under datasketches/tests and use two entry-point patterns.

Sketch behavior tests

Non-serialization tests are grouped into one integration-test target per sketch. The target entry point is datasketches/tests/<sketch>_test/main.rs, with operation-specific modules such as update.rs, union.rs, or intersection.rs alongside it.

Because these entry points are nested below tests, Cargo does not discover them automatically. Each new sketch target must also be registered in datasketches/Cargo.toml with its required feature:

[[test]]
name = "tuple_test"
path = "tests/tuple_test/main.rs"
required-features = ["tuple"]

When adding a case to an existing sketch target, add it to the appropriate module and declare any new module from that target's main.rs; no Cargo manifest change is needed. Add another [[test]] entry only when introducing a new sketch target.

Serialization compatibility tests

Cargo automatically discovers datasketches/tests/serde_tests.rs, which aggregates the sketch-specific modules under datasketches/tests/serde_tests. Each module is gated by its corresponding sketch feature in serde_tests.rs.

To add serialization tests for another sketch, add serde_tests/<sketch>.rs and a feature-gated module declaration in serde_tests.rs. Do not add a separate [[test]] entry. Shared path handling belongs in serde_tests.rs, and serialization fixtures belong in the appropriate subdirectory under serde_tests.

Manual workflow (without xtask)

cargo x lint runs the following steps. Use these directly when you need more control or want to isolate failures:

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:

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:

cargo install taplo-cli typos-cli hawkeye

Serialization snapshots

Serialization compatibility tests use snapshots from a pinned revision of apache/datasketches-tck.

The cargo x prepare-testdata command downloads the TCK archive and synchronizes its snapshots into:

• datasketches/tests/serde_tests/cpp_generated_files
• datasketches/tests/serde_tests/go_generated_files
• datasketches/tests/serde_tests/java_generated_files

You can synchronize them separately:

cargo x prepare-testdata cpp
cargo x prepare-testdata go
cargo x prepare-testdata java

If no language is specified, all languages are prepared. These directories are not stored in Git. Run the command before the first test run and again whenever the pinned TCK revision changes. It requires network access and replaces the selected generated directories.

Code of Conduct

We expect all community members to follow our Code of Conduct.