# Contributing to Magent

Thanks for helping improve Magent. Small, reviewable changes with a clear reason
are the easiest to test and merge.

## Before opening an issue

- Use [SUPPORT.md](SUPPORT.md) to choose the right report type.
- Search existing issues and read the relevant installation guide.
- Remove credentials, tokens, email addresses, database content and private URLs.
- Use [SECURITY.md](SECURITY.md) for vulnerabilities; do not publish exploit details.

## Development setup

Use Python 3.14 and Node.js 24. Follow
[the foreground development guide](docs/LOCAL_DEVELOPMENT.md), use synthetic
data, and never connect tests to someone else's services.

## Quality checks

Backend:

```sh
python -m venv .venv
. .venv/bin/activate
pip install -r backend/requirements-dev.txt
python -m unittest discover -s backend/tests -p 'test_*.py'
python scripts/check_environment_docs.py
```

Frontend:

```sh
cd frontend
npm ci
npm test
npm run lint
npm run format:check
npm run typecheck
npm run build
```

Container changes should also pass both isolated smoke modes:

```sh
docker build -t magent:review .
bash scripts/ci_container_smoke.sh magent:review
MAGENT_SMOKE_MANAGED=true bash scripts/ci_container_smoke.sh magent:review
```

The smoke harness creates disposable containers, networks and volumes. Do not
aim it at a live instance or reuse a production volume.

## Pull requests

1. Base public work on the `release` branch.
2. Keep each pull request focused and explain the user-visible reason.
3. Add or update tests for behavior changes.
4. Update documentation and `CHANGELOG.md` when behavior or setup changes.
5. State exactly which checks ran and any platform limits or skipped checks.
6. Do not commit generated builds, `.env` files, logs, databases, backups or secrets.

By contributing, you agree that your contribution is licensed under the project's
[MIT License](LICENSE). Participation must follow the
[Code of Conduct](CODE_OF_CONDUCT.md).