guara/CONTRIBUTING.pt-BR.md

Contribuindo com o Guará

English · Português

Obrigado por ajudar! Regras de ouro:

1. Nunca escreva na origem. Qualquer código que abra um dispositivo deve usar source::open_path (somente leitura). PRs que escrevem no disco de origem são recusados.
2. Teste com dados reais. Novos detectores/leitores precisam de teste que recupera um arquivo conhecido bit a bit (veja crates/guara-core/tests/ e scripts/make-fixtures.sh).
3. Seja honesto sobre confiança. Se o conteúdo não puder ser validado, a confiança é no máximo média.
4. Código, comentários e commits 100% em inglês. Todo código-fonte, comentários, scripts, workflows de CI e mensagens de commit devem ser escritos em inglês, enquanto a interface gráfica/CLI permanece bilíngue (PT-BR e EN via i18n-en.js).

Fluxo

scripts/install-hooks.sh  # uma vez: ativa os hooks commit-msg e pre-push
scripts/check.sh          # rápido (segundos): fmt, clippy como no CI, tradução, scripts, workflows, semver
scripts/check.sh --full   # inclui cargo test --workspace e cargo audit

O CI leva de 5 a 30 minutos em Linux, então rode a verificação antes do push: quase tudo que faz o CI falhar aparece aqui em segundos. Mudanças só de documentação (*.md, docs/) pulam o CI.

No Linux os testes geram imagens com mtools, ntfs-3g, e2fsprogs, exfatprogs, imagemagick, zip e python3. Sem essas ferramentas os testes com imagem são ignorados (defina GUARA_REQUIRE_FIXTURES=1 para falhar).

Para as imagens de referência externas (BitLocker, FileVault 2, dfvfs, AFF4), rode scripts/fetch-testdata.sh; sem elas esses testes são pulados. O teste de BitLocker leva cerca de 75 s.

Releases e Versionamento

As versões seguem estritamente o Versionamento Semântico 2.0.0 (MAJOR.MINOR.PATCH), sincronizadas entre Cargo.toml, apps/gui/src-tauri/Cargo.toml e apps/gui/src-tauri/tauri.conf.json (validado por scripts/check.sh).

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 (x86_64 e aarch64) e Windows.

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.

Adicionando um formato de arquivo

Detectores simples ficam em crates/guara-core/src/signatures.rs; os mais novos, em formats.rs. Acrescente o detector em detect, o primeiro byte em might_start, a extensão em category_for_ext/matches_ext e um arquivo real ao scripts/make-fixtures.sh com teste de bit-exatidão.

Adicionando um sistema de arquivos

Crie o leitor em crates/guara-core/src/fs/, registre-o em fs/mod.rs e traga um teste com imagem real ou de referência. Não entregamos leitor sem validação: é por isso que ReFS e Storage Spaces ainda não existem. Imagens pequenas e sem dados pessoais são o melhor presente que se pode dar ao projeto.

Documentação

A versão principal é em inglês e cada arquivo tem uma tradução em português (*.pt-BR.md, docs/pt-BR/). Sem travessões. Ao mudar um recurso, atualize as duas versões (inglês e português) de docs/support.md, do CHANGELOG e, se for o caso, do ROADMAP.

As capturas de tela em docs/img são geradas: rode scripts/screenshots.sh para refazê-las a partir da versão atual (imagem de fotos sintética, varredura de verdade). Rode de novo sempre que a interface ou a versão exibida na tela mudar.

Commits

Os commits devem seguir Conventional Commits 1.0.0 em inglês (feat:, fix:, chore:, ci:, docs:, refactor:, test:, perf:, build:), ex.: fix(ntfs): handle sparse data runs correctly. Uma mudança lógica por PR. Validado automaticamente por .githooks/commit-msg.