# Contributing to Acauã

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

Thanks for helping. The project is an NDR engine built around deterministic evidence.
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 web dashboard remains bilingual (PT-BR and EN
   through `i18n-en.js`).

## Workflow

```bash
scripts/install-hooks.sh
scripts/fetch-libduckdb.sh ~/.cache/acaua/duckdb
export DUCKDB_LIB_DIR=~/.cache/acaua/duckdb LD_LIBRARY_PATH=~/.cache/acaua/duckdb
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, DuckDB version pin
verification and forbidden terms inspection. `--full` adds workspace tests and `cargo audit`.

## 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.

## 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.

Releases are published as multi-arch container images (`linux/amd64` and `linux/arm64`)
to the Gitea registry. Pushing a `v*` tag creates a Gitea Release from the matching
`CHANGELOG.md` section and tags the existing container image.

## License

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