# Contributing

> Keep changes focused, respect data-handling boundaries, and run the local checks before opening a PR.

*Canonical HTML: https://grassmarlin.com/wiki/contributing/*
*Markdown source: https://grassmarlin.com/wiki/contributing.md*
*Français: https://grassmarlin.com/fr/wiki/contributing.md*

---

The contribution guide is intentionally pragmatic: keep PRs small, do not commit captures or secrets, and understand which future repo boundary your change belongs to.

**Focused changes**, Small PRs are easier to review than broad refactors.

**Run local checks**, At minimum, run the Python syntax check before opening a PR.

**No sensitive data**, Do not commit captures, secrets, or private environment details.

## Before you start

- Open issues or small discussion threads are welcome for bugs, parser gaps, UI problems, and deployment improvements.
- Keep changes focused rather than mixing many unrelated concerns.
- Avoid committing private captures, secrets, ad hoc local screenshots, or local tool metadata.
- Documentation screenshots under `docs/screenshots/` are the explicit exception to the no-screenshot rule.

## Development notes

The canonical source files called out by the project are `_ms_engine.py`, `_auth.py`, `_models.py`, `_config.py`, and `app.py`. Compatibility shims such as `auth.py`, `models.py`, and `config.py` are not the primary source of truth.

The contribution guide also reinforces the project vocabulary:

- Rust engines handle packet-facing and event-heavy work.
- Python plugins handle report-facing analysis, enrichment, and triage logic.
- YAML rule packs handle declarative mappings, suppressions, and local policy.

## Suite workflow and subtree helpers

The suite repo keeps vendored component copies in subtree prefixes. The contribution docs call out helper commands for working with that model:

```
./scripts/update-subtrees.sh status
./scripts/sync-msengine-bootstrap.sh
```

The planned subtree prefixes are `msengine/`, `workbench/`, `plugins/`, and `engines/`. Today, `msengine/` is the first real bootstrap prefix.

## Local checks

Before opening a PR, the docs ask contributors to run the basic syntax check:

```
python3 -m py_compile app.py _auth.py _config.py _models.py _ms_engine.py
```

If you touched the bootstrap engine subtree, also verify the mirrored package entrypoint:

```
PYTHONPATH=msengine python3 -m msengine --help
```

If you made Docker-related changes, the guide also says to validate the stack locally:

```
docker compose up --build
```

## Security and data handling

- Do not commit secrets, `.env` files, infrastructure credentials, or internal deployment notes.
- Do not commit customer captures or bundled third-party PCAP corpora unless redistribution terms are explicitly documented.
- If you find a security issue, report it privately before opening a public issue.

The releases page tracks recent engine, UI, and live-viewer milestones so contributors can see where major shifts already happened. See [Releases](/wiki/releases.md) and [Repo family](/wiki/repo-family.md).

Source references: [CONTRIBUTING.md](https://github.com/eris-ot/marlinspike/blob/main/CONTRIBUTING.md)