# Contributing to Monata

Thanks for helping improve Monata. This project is a Python circuit workflow
layer with an ngspice-first native backend. External simulators, model
compilers, PDKs, and device models remain separate packages or user-provided
assets.

## Requirements

- Python 3.11 or newer
- Git
- Optional: ngspice on `PATH` for native simulator smoke tests

## Development Setup

```bash
git clone https://github.com/lizhangmai/monata.git
cd monata
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

Run the default source checks before opening a pull request:

```bash
pytest -q
ruff check src/monata tests
pyright src/monata tests
python -m build
twine check dist/*
```

In the full circuit workspace, use the editable pixi environment:

```bash
pixi run --manifest-path test/pixi.toml -e monata-dev test-monata-src
pixi run --manifest-path test/pixi.toml -e monata-dev ruff-monata-src
pixi run --manifest-path test/pixi.toml -e monata-dev pyright-monata-src
```

## Code Style

- Prefer small, behavior-preserving changes with focused tests.
- Use type hints for public APIs and shared internal helpers.
- Keep runtime dependencies intentional and reviewable. New GUI,
  documentation, cloud, simulator, compiler, or backend-specific dependencies
  need explicit maintainer review before they become package dependencies.
- Do not bundle PDKs, PTM files, foundry models, commercial model libraries, or
  third-party simulator/compiler source in Monata.
- Keep simulator integrations behind executable or registry boundaries.

The CI standard is `ruff check`, `pyright`, `pytest`, and distribution metadata
validation. Whole-repository formatting is not currently enforced.

## Tests

- Add regression tests for bug fixes.
- Add focused unit tests for new behavior and broader tests when changing
  shared contracts such as `SimTask`, `SimResult`, model manifests, workspace
  persistence, or the ngspice backend.
- Tests that require an external executable should skip cleanly when the tool is
  not available.
- Preserve the existing behavior that ordinary simulator failures return
  structured failed `SimResult` objects where practical.

## Pull Requests

Keep pull requests reviewable:

- Explain the user-facing reason for the change.
- Include tests or a clear explanation when tests are not applicable.
- Update the package README or related docs pages when behavior, dependencies,
  or supported scope changes.
- Do not introduce new simulator backends without an explicit design and
  maintainer review.

## Reporting Issues

Use GitHub issues for ordinary bugs and feature requests. Include:

- OS and Python version
- Monata version or commit
- Simulator backend and executable version, if relevant
- Minimal reproduction code or netlist
- Full failure message or structured `SimResult.metadata`

Report security issues privately through the channel described in
{doc}`security`.