Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
133 lines (87 loc) · 3.62 KB

CONTRIBUTING.md

File metadata and controls

133 lines (87 loc) · 3.62 KB
Raw

Contributing to Audex

Thanks for your interest in contributing to Audex! This document covers everything you need to get started.

Getting Started

Prerequisites

  • Rust 1.85+ (the minimum supported Rust version)
  • Git

Optional, depending on what you're working on:

  • Nightly Rust — required for fuzzing (rustup install nightly)
  • wasm-pack 0.13.1 — required for WASM builds
  • Node.js — required for running WASM examples

Building

git clone https://github.com/bakgio/audex.git
cd audex

# Build with default features
cargo build

# Build with all features
cargo build --all-features

Running Tests

# Run the full test suite (recommended)
cargo test --all-features

# Run a specific test
cargo test --all-features test_flac_read_write

# Run WASM tests (requires wasm-pack and Node.js)
cd wasm && wasm-pack test --node

Linting and Formatting

CI enforces both — run these before submitting a PR:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Making Changes

Bug Fixes

  1. Open an issue describing the bug (if one doesn't exist already).
  2. Include a minimal reproducing case — ideally a test file or byte sequence.
  3. Write a regression test that fails without the fix and passes with it.
  4. Submit a PR referencing the issue.

New Format Support

If you're adding support for a new audio format:

  1. Add the parser/writer in src/ following the existing format modules as a guide.
  2. Add integration tests in tests/ with sample audio files in tests/data/.
  3. Add both sync and async fuzz targets in fuzz/fuzz_targets/.
  4. Update the format table in README.md.

New Features

For larger changes, open an issue first to discuss the design. This saves everyone time if the approach needs adjustment.

Code Guidelines

  • Follow existing code style — cargo fmt handles formatting.
  • All public API items should have doc comments.
  • Keep unsafe usage to an absolute minimum. If you must use it, explain why in a comment.
  • Parsers must handle malformed input gracefully — return errors, don't panic. The fuzz suite will catch these.

Testing

Test Fixtures

Test audio files live in tests/data/. When adding new ones:

  • Keep files as small as possible (a few KB is ideal).
  • Include only the minimum metadata needed for the test.
  • Do not commit copyrighted audio content.

Fuzzing

If your change touches any parser or writer code, run the relevant fuzz target:

cargo +nightly fuzz run fuzz_<format> -- \
    -rss_limit_mb=512 \
    -max_len=1048576 \
    -timeout=10 \
    -max_total_time=300

See fuzz/README.md for the full list of targets and recommended flags.

Note: Fuzzing requires Linux or macOS (or WSL on Windows).

WASM

If your change affects the public API, check that the WASM bindings still compile and pass tests:

cd wasm

# Compile check
cargo check --target wasm32-unknown-unknown

# Run WASM integration tests (requires wasm-pack 0.13.1 and Node.js)
wasm-pack test --node

Submitting a Pull Request

  1. Fork the repo and create a branch from main.
  2. Make your changes — keep commits focused and well-described.
  3. Ensure cargo test --all-features, cargo fmt, and cargo clippy all pass.
  4. Open a PR against main with a clear description of what changed and why.

CI runs automatically on all PRs. All checks must pass before merge.

License

By contributing to Audex, you agree that your contributions will be dual-licensed under MIT and Apache 2.0, as described in the README.