bloomcraft 0.1.0

Production-grade Bloom filter library for Rust with concurrent variants and optimal performance
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# Contributing to BloomCraft

BloomCraft is authored and maintained by Zaud Rehman.

Bug reports, API feedback, and pull requests are welcome. This document covers
everything you need to get a contribution merged cleanly.

---

## Reporting Issues

Open an issue at [github.com/ZaudRehman/bloomcraft/issues](https://github.com/ZaudRehman/bloomcraft/issues).

Use the appropriate label:

| Label | Use for |
|---|---|
| `bug` | Incorrect behavior, wrong FPR, panics in safe code |
| `enhancement` | New filter variant, API addition, performance improvement |
| `question` | Usage questions, design rationale, architecture clarification |
| `documentation` | Missing, incorrect, or unclear docs |

For bugs, include:
- Rust version (`rustc --version`)
- BloomCraft version and active feature flags
- A minimal reproduction (ideally a failing `#[test]`)
- The observed vs. expected behavior

---

## Pull Requests

Target the `main` branch for all PRs. Before opening one:

1. **Run the full test suite locally:**
   ```bash
   cargo test --all-features
   ```

2. **Run clippy - zero warnings expected:**
   ```bash
   cargo clippy --all-features -- -D warnings
   ```

3. **Run the benchmarks if your change touches a hot path:**
   ```bash
   cargo bench
   ```

### Checklist

Every PR must satisfy all of the following before it will be reviewed:

- [ ] All existing tests pass (`cargo test --all-features`)
- [ ] New public API items have `///` doc comments with at least one runnable example
- [ ] New behavior has unit tests covering the happy path and at least one edge case
- [ ] An entry has been added to `CHANGELOG.md`
- [ ] No new `clippy` warnings are introduced

### Adding a New Filter Variant

New filter types carry a higher bar:

- Implement `BloomFilter<T>` fully - no methods may be left as stubs or delegations that silently drop data
- Provide an integration test in `tests/` in addition to unit tests in the module
- Add the variant to the filter selection table and filter variant section in `README.md`
- Add it to the `test_all_filters_accessible` test in `filters/mod.rs`
- Confirm it implements `Send + Sync` and add it to `test_filters_are_send_sync`

### Unsafe Code Policy

Any new `unsafe` block must include a `// SAFETY:` comment that explains:

1. What invariant makes the operation sound
2. Why that invariant holds at this call site
3. What would break if a caller violated it

PRs that introduce `unsafe` without this justification will not be merged,
regardless of whether the code appears correct.

---

## MSRV Policy

BloomCraft targets **Rust 1.73**. Do not use features stabilized after that
version without a corresponding update to:

- The badge in `README.md`
- The `rust-version` field in `Cargo.toml`
- The CI matrix in `.github/workflows/`

---

## Commit Style

Use the [Conventional Commits](https://www.conventionalcommits.org/) format:

```
feat(filters): add XorBloomFilter variant
fix(scalable): correct fill-rate calculation under Bounded growth
docs(readme): add AtomicPartitionedBloomFilter example
perf(striped): replace modulo with Lemire range reduction
test(counting): add overflow boundary test for 4-bit counter
```

Scope is the module name (`filters`, `sync`, `builder`, `hash`, `metrics`, `serde`).

---

## License

By contributing, you agree that your contributions may be distributed under the repository’s existing MIT OR Apache-2.0 license terms, unless you explicitly state otherwise in writing.