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

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:

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:

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 Security Policy.