Contributing¶

Contributions to DigSim are welcome, big and small: bug reports, ideas, documentation, examples, new components and fixes. DigSim is developed on GitHub.

Reporting bugs and suggesting ideas¶

Open an issue. For a bug, please include:

the DigSim version (digsim-logic-simulator --version), your operating system and Python version,
what you did, what you expected and what happened instead, with the full error message,
the circuit file or Python script that shows the problem, if you have one.

Ideas and questions are welcome as issues too.

Development setup¶

DigSim uses uv for development.

Fork the repository on GitHub and clone your fork:

git clone https://github.com/<your-user>/digsim.git
cd digsim

Create the virtual environment, with DigSim installed in editable mode:
```
uv sync
```
Start the application from the source tree, so your changes take effect directly:
```
uv run -m digsim.app
```

Where things are¶

Path	Contents
`src/digsim/circuit/`	The simulator: `Circuit`, components and ports (`components/atoms/`)
`src/digsim/app/`	The GUI application: main window (`gui/`), component drawing (`gui_objects/`), model and settings dialogs
`src/digsim/synth/`, `src/digsim/utils/`	Yosys synthesis and netlist parsing
`src/digsim/storage_model/`	The file format for saved circuits
`tests/`	The tests
`examples/`, `example_circuits/`	Python examples and GUI circuits, see Examples
`docs/`	This documentation

To add a component, follow Creating Components.

Before you submit¶

Run the same checks as the continuous integration, from the repository root:

uv tool run ruff format                        # format the code
uv tool run ruff check                         # lint
uv run --with mypy mypy                        # type check
uv run --with pytest pytest                    # run the tests

The tests run on Linux with Python 3.10 to 3.14 and on Windows, so avoid syntax newer than Python 3.10.

For documentation changes, preview the site while you edit it, at http://127.0.0.1:8000/digsim/:

uv tool run --with mkdocs-material mkdocs serve

If you change an example, regenerate the images on the Examples page:

uv run --with pytest python docs/scripts/generate_examples.py

Guidelines¶

Keep changes focused. One fix or feature per pull request, and one purpose per commit, makes changes easy to review.
Explain why. Commit messages and pull request descriptions should say what was wrong or missing, not only what the code does.
Add tests for new components and bug fixes in tests/.
Annotate types. All functions have type annotations, and mypy rejects functions without them.
Use full Qt enum names, such as Qt.GlobalColor.red instead of Qt.red.
Update the documentation when you change behavior, and add a line to the top section of CHANGELOG.md for user-visible changes.

Submitting a pull request¶

Create a branch in your fork for the change: git switch -c my-change.
Commit your changes and push the branch to your fork.
Open a pull request against the main branch, describing what the change does and why.
The Ruff check runs on the pull request. The tests run when you push to a repository with GitHub Actions enabled, so enable Actions in your fork to see them before you open the pull request.

DigSim is licensed under the Clear BSD License, and your contributions are licensed under the same terms.