# Contributing to Acauã

**English** · [Português](CONTRIBUTING.pt-BR.md)

Thanks for helping. The project is a pre-alpha skeleton, so the most useful
contributions right now are tests, fixtures, documentation and small,
well-scoped design corrections.

1. **Authorized monitoring only.** Acauã is defensive software for networks you
   own or are explicitly authorized to observe. Do not add collection paths that
   hide scope, retention or evidence.
2. **Evidence is part of the feature.** A detection change must state its
   inputs, fixed-order reductions and intermediate values. A score without a
   reproducible evidence record is not accepted.
3. **Be honest about what works.** If a feature is a stub, Linux-only or limited
   to one Zeek log, say so in the README, the CLI help and the test.
4. **100% English codebase.** Source code, comments, scripts, workflows and
   commit messages are English. The GUI and CLI remain bilingual (PT-BR and EN
   through `i18n-en.js`).

## Workflow

```bash
scripts/install-hooks.sh
scripts/check.sh
scripts/check.sh --full
```

`check.sh` runs formatting, clippy with warnings as errors, UI translation
coverage, shell syntax, workflow YAML, SemVer consistency and the desktop check.
`--full` adds workspace tests and `cargo audit`.

The optional DuckDB feature is not part of the default check:

```bash
cargo check -p acaua-core --features duckdb
```

## Research

`research/` is an isolated Python workspace for scientific validation. It may
use astropy, scipy, networkx, pandas and notebooks. It must never be imported by
the Rust runtime, copied into a release or required to build the product.

## Detection rules

- Keep reductions in a fixed order when floating-point results are part of an
  alert.
- Use a documented sentinel instead of `NaN` or a panic for degenerate inputs.
- Use Jensen-Shannon, not raw KL, when a distribution can contain zero
  probability.
- Do not use JA4S/JA4H/JA4X/JA4SSH/JA4L by default: those variants carry a
  non-OSI license. The client TLS JA4 fingerprint is the only default.
- Long connections need their own detector; they do not produce the short
  intervals a beaconing score expects.

## Interface and translation

The interface source text is Portuguese. English comes from
`apps/gui/ui/i18n-en.js`, applied at runtime by `i18n.js`. When adding visible
text, run `node scripts/check-ui-i18n.mjs` and include the English pair.

## Documentation

Keep the pair: every `*.md` and `docs/*` file has an English version and a
Portuguese version (`*.pt-BR.md`, `docs/pt-BR/`). File names are translated only
when the word actually changes, as in `architecture.md` → `arquitetura.md`.

## Commits and releases

Commits follow Conventional Commits 1.0.0 in English (`feat:`, `fix:`, `chore:`,
`ci:`, `docs:`, `refactor:`, `test:`, `perf:`, `build:`). Versions follow SemVer
2.0.0 and are synchronized across the workspace, the desktop manifest and the
Tauri config.

Pushing a `v*` tag creates a Gitea Release from the matching `CHANGELOG.md`
section and attaches the Linux CLI packages plus the desktop bundles.

## License

By contributing, you agree to license under [MIT](LICENSE-MIT) **or**
[Apache-2.0](LICENSE-APACHE), like the rest of the project.