sabia/CONTRIBUTING.pt-BR.md

Contribuindo com o Sabiá

English · Português

Obrigado por ajudar! Regras de ouro:

1. Só auditoria autorizada. Todo recurso novo é para testar redes próprias ou com autorização. Operações sensíveis (desautenticação) exigem confirmação explícita e ficam na trilha de auditoria. PRs que escondem atividade da trilha ou removem as confirmações são recusados.
2. Teste os parsers com dados reais. Novos leitores (radiotap, 802.11, EAPOL, pcap) precisam de teste com quadros conhecidos — veja crates/sabia-core/tests/ e os ajudantes em crates/sabia-core/src/testutil.rs. Nada de parser sem teste.
3. Seja honesto sobre o que funciona. Se um recurso só roda no Linux, ou só cobre WPA2-PSK, diga isso no --help, no README e no teste.

Fluxo

cargo fmt --all
cargo clippy --workspace --all-targets   # como no CI (RUSTFLAGS=-D warnings)
cargo test --workspace
node scripts/check-ui-i18n.mjs            # cobertura da tradução da interface

O CI roda só em Linux (o Gitea tem um único runner); rode esses comandos antes do push — quase tudo que faz o CI falhar aparece aqui em segundos. Mudanças só de documentação (*.md, docs/) são leves no CI.

A captura ao vivo só existe no Linux (AF_PACKET + netlink); o código dos caminhos de Windows e macOS continua compilando e é coberto pelo cargo check, mas não roda no CI nem é compilado para release. são offline.

Releases

Enviar uma tag v* faz o CI do Gitea criar a release (as notas vêm do CHANGELOG.md, então atualize-o antes) e anexar o CLI para Linux (x86_64 e aarch64) e o app desktop para Linux aarch64 e Windows. O runner é arm64, então o app Linux x86_64 vem de uma máquina Linux x86_64:

scripts/build-gui.sh linux          # AppImage + .deb em dist-gui/
API=https://git.lucasrguerra.dev.br/api/v1/repos/lucasrguerra/sabia TOKEN=... \
  scripts/release-upload.sh vX.Y.Z dist-gui/*

Não há build para macOS: ele exige o SDK e a assinatura da Apple, que um runner Linux não tem.

Onde mexer

Mapa dos módulos em docs/pt-BR/arquitetura.md. O que falta e o que é bem-vindo está no ROADMAP.

• Parsing de quadros: radiotap.rs, dot11.rs, eapol.rs.
• Rádio e sistema: iface.rs, netlink.rs, scan.rs, capture.rs, inject.rs.
• Handshake e quebra: handshake.rs, crack.rs.
• App e API: crates/sabia-cli/src/ e apps/gui/.

Interface e tradução

O texto-fonte da interface é em português; o inglês vem de apps/gui/ui/i18n-en.js, aplicado em tempo de execução por i18n.js. Ao adicionar ou mudar texto visível, rode node scripts/check-ui-i18n.mjs e inclua a tradução — o CI recusa português sem par em inglês. Não traduza dados do usuário (SSID, BSSID, valores) nem termos técnicos (WPA, EAPOL, pcap…).

Documentação

Mantenha o par pt/en: todo arquivo *.md e docs/* tem a versão em português (*.pt-BR.md, docs/pt-BR/) e em inglês.

Licença

Ao contribuir, você concorda em licenciar sob MIT ou Apache-2.0, como o resto do projeto.