# Contributing to Bearing

## Project Status

Bearing is a personal project — a Rust port of Apache Lucene. Pull requests are **not currently accepted**. You're welcome to fork and make it your own.

## Building & Testing

```bash
cargo build            # debug build
cargo test             # run all tests
cargo clippy           # lint (warnings should be zero)
cargo fmt              # format code
```

Full end-to-end test (requires Java 21+; Gradle handles the Lucene dependency):

```bash
./tests/e2e_indexfiles.sh
```

## Coding Conventions

See [`CLAUDE.md`](CLAUDE.md) for the authoritative style guide, including error handling, module layout, byte order rules, and naming conventions.

## Porting Methodology

Bearing is a port of **Apache Lucene 10.3.2**. Lucene is the source of truth for **behavior and storage formats** — the on-disk output must be compatible. However, the Rust code should be idiomatic Rust, not a transliteration of Java. Prefer traits, enums, and Rust's ownership model over mirroring Java's object hierarchy. Codec version naming (e.g., `lucene90`, `lucene103`) follows the Java convention.

To set up the reference sources:

```bash
./reference/download-references.sh
```

When porting a feature, locate the corresponding Java source under `reference/lucene-10.3.2/lucene/` and port both the implementation and its tests.

## Dependency Policy

Bearing uses very limited runtime dependencies and we strive to avoid adding more. At the same time, try not to reimplement common libraries.

## Test Data

`testdata/docs/` has 4 small files for quick tests. `testdata/impact-docs/` has 150 documents for impact/feature testing. Generate a larger corpus for benchmarking:

```bash
python3 testdata/gen_docs.py -n 2000    # generates to /tmp/perf-docs/
```

## E2E Tests

Roundtrip tests: Bearing writes indexes, Java Lucene reads and validates them.

```bash
./tests/e2e_all.sh              # run all e2e tests
./tests/e2e_indexfiles.sh       # basic indexing roundtrip
./tests/e2e_doc_values.sh       # doc values byte-level comparison
./tests/e2e_verify_impacts.sh   # feature field / impact encoding
./tests/e2e_verify_tim_compression.sh  # terms dictionary compression
```

Requires Java 21+. Gradle handles the Lucene dependency automatically.

## Performance Comparison

Compare indexing speed and correctness between Java Lucene and Rust:

```bash
./tests/compare_index_perf.sh -release --threads 12
./tests/compare_index_perf.sh -docs /tmp/perf-docs -release
```

Compare query performance across Java and Rust on the same index:

```bash
./tests/compare_query_perf.sh -docs /tmp/gutenberg-small-2000
```

## If PRs Open in the Future

Contributions would need to:

- Pass `cargo test` (all tests)
- Pass `cargo clippy -- -D warnings` (no lint warnings)
- Be formatted with `cargo fmt`
- Include tests for new functionality
