guara/CONTRIBUTING.md

Contributing to Guará

English · Português

Thanks for helping! Golden rules:

1. Never write to the source. Any code that opens a device must use source::open_path (read-only). PRs that write to the source disk are rejected.
2. Test with real data. New detectors/readers need a test that recovers a known file bit for bit (see crates/guara-core/tests/ and scripts/make-fixtures.sh).
3. Be honest about confidence. If the content cannot be validated, confidence is at most medium.

Workflow

scripts/instalar-hooks.sh        # uma vez: roda a verificação rápida antes de cada push
scripts/verificar.sh             # rápido (segundos): fmt, clippy como no CI, tradução, scripts, workflows
scripts/verificar.sh --completo  # inclui cargo test --workspace e cargo audit

The CI takes 5 to 30 minutes on three systems, so run the check before pushing: almost everything that makes the CI fail shows up locally in seconds. Documentation-only changes (*.md, docs/) skip the CI.

On Linux the tests build images with mtools, ntfs-3g, e2fsprogs, exfatprogs, imagemagick, zip and python3. Without these tools the image tests are skipped (set GUARA_REQUIRE_FIXTURES=1 to make them fail).

For the external reference images (BitLocker, FileVault 2, dfvfs, AFF4), run scripts/fetch-testdata.sh; without them those tests are skipped. The BitLocker test takes about 75 s.

The desktop app signs its update packages: tauri.conf.json has createUpdaterArtifacts on, so a local tauri build needs TAURI_SIGNING_PRIVATE_KEY (any key made with tauri signer generate; the release key lives only in the repository secrets). For a quick local bundle, pass --config '{"bundle":{"createUpdaterArtifacts":false}}'.

Releases

Pushing a v* tag makes the Gitea CI create the release (notes come from CHANGELOG.md, so update it first), attach the Linux CLI (x86_64 and aarch64), the desktop app for Linux aarch64 and Windows, and build the updater's latest.json. The runner is arm64, so the Linux x86_64 desktop app comes from an x86_64 Linux machine:

scripts/build-gui.sh linux          # AppImage + .deb (signed) in dist-gui/
API=https://git.lucasrguerra.dev.br/api/v1/repos/lucasrguerra/guara TOKEN=... \
  scripts/release-upload.sh vX.Y.Z dist-gui/*
API=... TOKEN=... python3 scripts/make-latest-json.py vX.Y.Z notes.md latest.json   # then upload it too

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

Where to make changes

A map of the modules is in docs/architecture.md. What is missing and what is welcome is in the ROADMAP.

Adding a file format

Simple detectors live in crates/guara-core/src/signatures.rs; the newer ones in formats.rs. Add the detector to detect, the first byte to might_start, the extension to category_for_ext/matches_ext and a real file to scripts/make-fixtures.sh with a bit-exactness test.

Adding a file system

Create the reader in crates/guara-core/src/fs/, register it in fs/mod.rs and bring a test with a real or reference image. We do not ship a reader without validation: that is why ReFS and Storage Spaces do not exist yet. Small images without personal data are the best gift you can give the project.

Documentation

The main version is in English and every file has a Portuguese translation (*.pt-BR.md, docs/pt-BR/). No em dashes or en dashes. When you change a feature, update both versions (English and Portuguese) of docs/support.md, the CHANGELOG and, if applicable, the ROADMAP.

Commits

Short messages in the imperative (fix reading of sparse runs in NTFS). One logical change per PR.