Contributing to Circuit-Synth

Thank you for your interest in contributing to circuit-synth.

Development Setup

  1. Clone the repository:

git clone https://github.com/circuit-synth/circuit-synth.git
cd circuit-synth

  1. Install dependencies:

uv sync

  1. Run tests:

./tools/testing/run_full_regression_tests.py

  1. (Optional) Register Claude Code agents:

uv run register-agents

Development Workflow

  1. Create a feature branch from develop

  2. Make your changes with tests

  3. Run the test suite: ./tools/testing/run_full_regression_tests.py

  4. Submit a pull request to develop

Code Style

  • Python: Use black, isort, mypy, flake8

  • Write tests for new functionality

  • Update documentation as needed

Quick Start Options

1. Add a Circuit Example (15 mins)

Create a new example in examples/ showing a common circuit pattern:

# examples/led_driver.py
from circuit_synth import *

@circuit(name="led_driver")
def led_driver():
    """LED with current limiting resistor."""
    led = Component("Device:LED", ref="D")
    resistor = Component("Device:R", ref="R", value="220")
    
    VCC = Net('VCC')
    GND = Net('GND')
    
    resistor[1] += VCC
    resistor[2] += led[1]  
    led[2] += GND

  • Component processing (Issue #40) - 97% of generation time

  • Netlist processing (Issue #36)

  • KiCad parsing (Issue #37)

3. Component Search Improvements

Extend manufacturing integrations in src/circuit_synth/manufacturing/:

  • Add Digi-Key support

  • Improve JLCPCB filtering

  • Add alternative component suggestions

Development Environment Setup

# Clone and install
git clone https://github.com/circuit-synth/circuit-synth.git
cd circuit-synth
uv sync

# Run tests
uv run pytest

Development Workflow

  1. Fork and clone the repository

  2. Create a feature branch: git checkout -b feature/your-feature

  3. Make changes following existing patterns

  4. Test: ./tools/testing/run_full_regression_tests.py

  5. Format: black src/ && isort src/

  6. Push and create a pull request

Testing

# Run all tests
./tools/testing/run_full_regression_tests.py

# Python tests only
uv run pytest --cov=circuit_synth

# Specific test
uv run pytest tests/unit/test_core_circuit.py -v

We follow Test-Driven Development (TDD):

  1. Write tests first

  2. Make them pass with minimal code

  3. Refactor while keeping tests green

Types of Contributions

Bug Reports

Include:

  • Circuit-synth version

  • Minimal reproduction code

  • Error messages

  • Expected vs actual behavior

Feature Requests

  • Describe the problem being solved

  • Provide use cases

  • Consider implementation complexity

Code Contributions

  1. Discuss in an issue first

  2. Follow code standards (black, mypy, flake8)

  3. Add tests for new features

  4. Update documentation

Code Style

  • Follow PEP 8 (88 char line length)

  • Use type hints for public functions

  • Write docstrings for public APIs

  • No bare except clauses

Architecture

Circuit-synth uses a JSON-centric architecture:

  • Python β†’ JSON β†’ KiCad for circuit generation

  • KiCad β†’ JSON β†’ Python for round-trip conversion

  • JSON serves as the canonical data format

Key directories:

  • src/circuit_synth/core/ - Core circuit classes

  • src/circuit_synth/kicad/ - KiCad file I/O

  • src/circuit_synth/manufacturing/ - JLCPCB integration

  1. Use pure Python for all functionality

  2. Focus on readability and maintainability

High-impact areas:

  • Component processing (97% of time)

  • Netlist generation

  • KiCad parsing

Pull Request Guidelines

  • Reference related issues (β€œFixes #123”)

  • Include tests for new features

  • Update documentation as needed

  • Ensure all CI checks pass

We review PRs within 48 hours and provide constructive feedback.

Getting Help

Code of Conduct

We are committed to a welcoming environment for all contributors.

  • Be respectful and constructive

  • Accept feedback gracefully

  • Focus on what’s best for the community

Recognition

Significant contributors are:

  • Added to CONTRIBUTORS.md

  • Mentioned in release notes

  • Credited in documentation

Thank you for contributing to Circuit-Synth!