CONTRIBUTING.md

Contributing

Thanks for contributing to arena-alligator.

Development workflow

This repository uses mise as the task runner. Run all project tasks through mise.

List tasks:

mise tasks --all

Most common commands:

mise run format:fix
mise run clippy
mise run test

Local validation before PR

Run the full local validation path before opening a pull request:

mise run test

For faster iteration during development:

mise run test:nextest
mise run format
mise run clippy

Benchmarks

Benchmarks are not required for most PRs. Run them when allocator behavior, contention behavior, or performance-sensitive paths change.

mise run bench
mise run bench:extreme

Benchmark documentation and latest published summaries:

• Benchmark results

Pull requests

Keep PRs focused and small. Include:

1. A concise problem statement.
2. The behavioral change.
3. Validation performed (tests/bench commands run).

If relevant, include before/after benchmark deltas and platform details (CPU, architecture, OS, thread count).

Style

• Follow rustfmt output.
• Treat clippy warnings as errors for contributions.
• Prefer clear naming and small, composable functions over large multi-purpose blocks.

Atomic and alignment invariants

Changes touching atomics, memory ordering, or alignment-sensitive structures must preserve the crate's concurrency and layout assumptions.

• Keep allocator synchronization lock-free and atomic-based (no mutex substitution in hot allocation paths).
• Treat src/bitmap.rs CacheAligned<T> wrappers as false-sharing guards; do not remove or reduce alignment without benchmark evidence.
• Keep slot/alignment inputs power-of-two validated for builders (FixedArena/BuddyArena), and preserve capacity rounding behavior.
• If changing atomic orderings, document why the new ordering is correct and which happens-before edge still protects safety/liveness.

Required evidence for these changes (in PR description):

1. A clear problem statement tied to a concrete invariant (safety, liveness, or performance regression).
2. A minimal reproducible case that demonstrates the issue before the change.
3. Exact commands used to reproduce, including feature flags, thread counts, and environment details.
4. Before/after output showing the issue is fixed (or regression removed) by the change.

Evidence must be reproducible by another contributor on comparable hardware/settings.

Required validation commands:

mise run test
mise run test:nextest
mise run clippy

If contention behavior or bitmap internals change, also run:

mise run bench