# Contributing to sorug
Thank you for your interest in contributing. sorug aims to be a reference-grade WHATWG URL parser: **correct first**, then relentlessly fast, without compromising memory safety.
By participating, you agree to uphold the [Code of Conduct](CODE_OF_CONDUCT.md).
## Project principles (non-negotiable)
1. **WHATWG compliance** — Behavior follows the [URL Living Standard](https://url.spec.whatwg.org/). WPT regressions are blockers.
2. **Zero-copy by default** — Prefer borrowing the input serialization. Allocate only when the algorithm requires mutation or non-ASCII processing.
3. **`forbid(unsafe_code)`** — Library code in the main `sorug` crate must not introduce `unsafe`. The crate enforces this via `[lints.rust] unsafe_code = "forbid"` in `Cargo.toml`. Do not add `#![allow(unsafe_code)]` or equivalent workarounds in `sorug`. C ABI lives only in the separate workspace member [`ffi/`](ffi/) (`sorug-ffi`).
4. **No bloat** — Avoid heavy Unicode / IDNA crates when a focused in-tree implementation suffices. Dependencies must earn their weight on the hot path. IDNA **membership** tables are generated at build time from vendored Unicode UCD files under [`data/ucd/`](data/ucd/) plus [`data/idna_overlay.txt`](data/idna_overlay.txt) (see [`scripts/refresh-ucd.sh`](scripts/refresh-ucd.sh)); do not add ICU/`idna`/`unicode-bidi` for that.
Pull requests that trade these principles for micro-benchmarks will be declined.
## Development setup
Requirements:
- Rust **1.85+** (see `rust-version` in `Cargo.toml`)
- A recent stable toolchain (`rustup update stable`)
Clone and build:
```bash
git clone https://github.com/hocestnonsatis/sorug.git
cd sorug
cargo build
```
## Tests
Run the full suite (unit tests, WPT, comprehensive validation):
```bash
cargo test
```
WPT only (`tests/urltestdata.json`):
```bash
cargo test --test wpt
```
Security / IP / path / differential checks:
```bash
cargo test --test comprehensive_validation
```
All of the above must pass before a PR is mergeable. If you intentionally diverge from rust-url on a WPT-correct edge case, document it in the differential allowlist (see `tests/comprehensive_validation.rs`) and explain why in the PR.
### IDNA tables / Unicode refresh
Membership classifiers (`disallowed`, CheckBidi helpers, UTS #46 ignored/needs-map, …) are **not** hand-edited range lists. `build.rs` derives them from pinned files in `data/ucd/` and merges Node/WPT deltas from `data/idna_overlay.txt`.
```bash
./scripts/refresh-ucd.sh 16.0.0 # or another Unicode version
cargo test --test wpt --test wpt_setters
```
Fuzzing (`fuzz/`) is for crash + differential invariants against rust-url — see [`fuzz/README.md`](fuzz/README.md). Do not treat corpus hits as a mandate to grow overlay ranges without a Node/WPT rationale.
## Benchmarks
Criterion benches live in `benches/url_benchmark.rs` and compare sorug against ada-url and servo/`url`:
```bash
cargo bench --bench url_benchmark
```
Guidelines:
- Prefer reporting **relative** change on the same machine over absolute nanoseconds in PR descriptions.
- Do not regress Fast Path ASCII, Complex Query, or File Edge Case without a strong correctness rationale.
- IDNA leads peers after the in-tree Punycode / direct-append path; large swings deserve investigation.
## Coding standards
- Follow existing module layout under `src/parser/` (`fast`, `scan`, `host`, `percent`, `punycode`, `serialization`).
- Prefer clear state-machine transitions over clever one-liners on the parser path.
- Run Clippy locally; pedantic lints are enabled at `warn`:
```bash
cargo clippy --all-targets -- -D warnings
```
- Format with `rustfmt`:
```bash
cargo fmt --all
```
## Pull request checklist
- [ ] `cargo test` / `cargo test --workspace` passes (including WPT and `sorug-ffi`).
- [ ] No new `unsafe` in the main `sorug` crate and no lint overrides that weaken `forbid(unsafe_code)` there (FFI changes belong in `ffi/`).
- [ ] Zero-copy / CoW invariants preserved for ASCII-canonical inputs.
- [ ] Benchmarks run if the change touches the hot path; summarize deltas.
- [ ] Public API changes are documented and called out (breaking changes must be explicit).
- [ ] New behavior covered by tests (WPT case, unit test, or comprehensive validation).
## Issues and discussion
- Bug reports: include the input string, expected vs actual `href` / components, and whether rust-url / ada agree.
- Performance ideas: include a minimal repro and Criterion snippets when possible.
- Security-sensitive URL parsing bugs: prefer a private GitHub Security Advisory if disclosure could be harmful; otherwise open an issue with a clear repro.
## License of contributions
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in sorug is dual-licensed under **MIT OR Apache-2.0**, the same as the project.