How to Contribute

How to Contribute Code

The litchi project welcomes contributions ranging from typo fixes to major parser features. This guide describes the day-to-day workflow maintainers expect from contributors.

Development Workflow

1. Discuss before you dig – comment on an existing issue or open a new one to describe the problem you plan to solve. Large design changes should include a short proposal so reviewers can validate the direction early.
2. Create a focused branch – branch names such as feature/xlsb-text-function or bugfix/ole-fib-csw-new make review and later archaeology easier.
3. Work in small, reviewable chunks – keep PRs tightly scoped (single feature or bug). When a change requires multiple stages, land them sequentially and keep each stage releasable.
4. Document as you go – update relevant wiki pages, markdown specs, and in-tree docs alongside code changes so knowledge stays fresh.

Prerequisites

Before writing code, make sure your local environment can build the full workspace.

Install Dependencies

• Rust toolchain – install the latest stable release via rustup. Enable rustfmt, clippy, and other components using rustup component add clippy rustfmt.
• System packages – ensure you have pkg-config, OpenSSL headers, and a modern C toolchain (GCC/Clang) for FFI-enabled crates and SIMD glue code.
• Optional feature tooling – some sub-crates rely on wasm32-unknown-unknown or aarch64 targets. Add them with rustup target add <triple> if you intend to work on those paths.
• Git hooks & linting – run cargo install cargo-nextest cargo-deny if you plan to work on CI parity locally.

Lint Your Code

• Run cargo fmt --all to enforce consistent formatting before every commit.
• Run cargo clippy --all-targets --all-features (or scoped to the features you touch) and fix or annotate warnings. We do not accept new clippy warnings unless you can justify them.
• Prefer idiomatic Rust patterns (iterators, match, borrowing). Avoid needless clones and use the common helper modules (SIMD, parsing utilities) whenever possible.

Testing your Changes

Automated tests are the primary safety net for regressions across file formats and feature flags.

Running Tests

• Run cargo test --workspace for a full check before opening a PR. For faster iterations, you can target individual crates with cargo test -p soapberry-zip or filter tests via cargo test name.
• Feature-flagged modules should be exercised with cargo test -p litchi --no-default-features --features ooxml,xlsb (substitute the flags relevant to your change).
• When fixing bugs or adding features, include regression tests (parser cases, writer snapshots, or formula engine unit tests) to demonstrate the behavior.

How to Open a Pull Request

Maintain a clean commit history and clear descriptions so reviewers can follow your reasoning.

Commit Your Changes

• Use imperative, descriptive commit messages (e.g., Implement XLSB conditional formatting ranges).
• Squash fixup commits locally when they only address review nits to keep history readable.

Push Your Changes

• Push your branch to your fork (or directly to the repo if you have access). Confirm CI pipelines pass or reproduce failures locally before requesting review.

Open a Pull Request

• Fill out the PR template completely, including problem statement, test evidence, and any docs updates. Link the relevant issue for traceability.
• Highlight breaking changes or feature flags affected so maintainers can plan releases.

Review and Address Feedback

• Respond to every review comment—either implement the change, explain a rationale, or convert the thread to a follow-up issue if it is out of scope.
• Re-run formatting, linting, and tests after applying feedback to avoid regressions.
• Mark conversations as resolved only when reviewers agree the concern is addressed.

How to Report a Bug

High-quality bug reports help maintainers reproduce and fix issues quickly.

Providing a Reproducer

1. Summarize the problem – include file format, platform, and whether the issue occurs when parsing or writing documents.
2. Share minimal inputs – attach the smallest sample file or paste the formula snippet that triggers the bug. If sensitive, describe the structure precisely so we can recreate it.
3. List exact steps – commands run (cargo run --example xlsb_dump sample.xlsb), feature flags, and any environment variables.
4. Include expected vs. actual behavior – describe what you thought would happen and what actually occurred (panic, malformed bytes, incorrect AST, etc.).
5. Add logs or stack traces – run with RUST_LOG=debug when possible and paste the relevant section inline or as an attachment.

The more precise your reproducer, the faster we can diagnose and deliver a fix.