sabia/CONTRIBUTING.md

Contributing to Sabiá

English · Português

Thanks for helping! Golden rules:

1. Authorized auditing only. Every new feature is for testing your own networks or networks you're authorized to test. Sensitive operations (deauthentication) require explicit confirmation and are recorded in the audit trail. PRs that hide activity from the trail or remove the confirmations are rejected.
2. Test the parsers with real data. New readers (radiotap, 802.11, EAPOL, pcap) need tests against known frames — see crates/sabia-core/tests/ and the helpers in crates/sabia-core/src/testutil.rs. No parser without a test.
3. Be honest about what works. If a feature is Linux-only, or only covers WPA2-PSK, say so in --help, in the README and in the test.
4. 100% English codebase and comments. All source code, comments, scripts, CI workflows, and commit messages must be written in English, while the GUI/CLI remains bilingual (PT-BR and EN via i18n-en.js).

Workflow

scripts/install-hooks.sh  # once: enables commit-msg and pre-push Git hooks
scripts/check.sh          # fast (seconds): fmt, clippy as in CI, i18n, scripts, workflows, semver
scripts/check.sh --full   # adds cargo test --workspace and cargo audit

CI runs on Linux; run the check before pushing: almost everything that fails CI shows up here in seconds. Documentation-only changes (*.md, docs/) skip CI.

Live capture exists only on Linux (AF_PACKET + netlink); the code behind Windows and macOS paths still compiles and is covered by cargo check.

Releases and Versioning

Versions strictly follow Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH), synchronized across Cargo.toml, apps/gui/src-tauri/Cargo.toml, and apps/gui/src-tauri/tauri.conf.json (enforced by scripts/check.sh).

Pushing a v* tag makes the Gitea CI create the release (notes come from CHANGELOG.md, so update it first) and attach the Linux CLI (x86_64 and aarch64) and the desktop app for Linux (x86_64 and aarch64) and Windows.

There is no macOS build: it needs Apple's SDK and code signing, which a Linux runner cannot provide.

Where to work

Module map in docs/architecture.md. What's missing and welcome is in the ROADMAP.

• Frame parsing: radiotap.rs, dot11.rs, eapol.rs.
• Radio and system: iface.rs, netlink.rs, scan.rs, capture.rs, inject.rs.
• Handshake and cracking: handshake.rs, crack.rs.
• App and API: crates/sabia-cli/src/ and apps/gui/.

Interface and translation

The source text of the interface is Portuguese; English comes from apps/gui/ui/i18n-en.js, applied at runtime by i18n.js. When adding or changing visible text, run node scripts/check-ui-i18n.mjs and include the translation — CI rejects Portuguese without an English pair. Don't translate user data (SSID, BSSID, values) or technical terms (WPA, EAPOL, pcap…).

Documentation

Keep the pt/en pair: every *.md and docs/* file has a Portuguese version (*.pt-BR.md, docs/pt-BR/) and an English one.

Commits

Commits must follow Conventional Commits 1.0.0 in English (feat:, fix:, chore:, ci:, docs:, refactor:, test:, perf:, build:), e.g. fix(eapol): validate replay counter on message 2. One logical change per PR. Enforced automatically by .githooks/commit-msg.

License

By contributing, you agree to license under MIT or Apache-2.0, like the rest of the project.