Contributing¶

The canonical contributor guide lives in CONTRIBUTING.md at the repository root and is included verbatim below.

Contributing to qtest¶

First off — thank you for taking the time to contribute! This document walks you through everything you need to know to get a development environment up, make a change, run the test suite, and open a pull request.

By participating in this project you agree to abide by our Code of Conduct.

Ways to contribute¶

There are many ways to help — and writing code is only one of them:

Reporting bugs and producing minimal reproducers.
Improving documentation — typos, clearer examples, missing cross-references.
Triaging issues — reproducing reported bugs, asking the clarifying questions.
Writing tests — every additional property test makes the library more trustworthy.
Implementing features — see the issue tracker for ones tagged good first issue and help wanted.

If in doubt, open an issue to talk through your idea before writing code.

Development environment¶

We support Python 3.9 – 3.12 on Linux, macOS, and Windows. You’ll need a working Python install and git.

git clone https://github.com/metin-5115/qtest.git
cd qtest

python -m venv .venv
source .venv/bin/activate           # Linux / macOS
.venv\Scripts\activate              # Windows PowerShell

pip install -e ".[dev]"
pre-commit install

The dev extra installs the formatter (black), linter (ruff), type checker (mypy), test runner (pytest, pytest-cov, pytest-xdist), and release tooling. pre-commit install wires up the formatting / linting hooks so each commit is pre-checked.

Project layout¶

qtest/
├── qtest/              # Library source code
│   ├── assertions/     # The four core assertions
│   ├── backends/       # Backend abstraction (Qiskit, Cirq, PennyLane)
│   ├── fixtures/       # pytest fixtures and plain factories
│   ├── metrics/        # Distances and statistical tests
│   ├── strategies/     # Hypothesis strategies
│   ├── plugin.py       # pytest plugin entry point
│   └── config.py
├── tests/              # Test suite (pytest)
├── examples/           # Runnable, documented usage examples
├── docs/               # Sphinx documentation
└── pyproject.toml      # Build, deps, and tool configuration

Running the test suite¶

A full local run is one command:

pytest

Useful variations:

pytest -m "not slow"                  # skip slow tests
pytest tests/test_assertions.py -v    # one file, verbose
pytest -n auto                        # parallel (via pytest-xdist)
pytest --cov=qtest --cov-report=term  # coverage report

Coverage is enforced on CI at ≥ 85 % for the project as a whole. PRs that drop coverage below that line will fail CI.

You can run the full quality suite (lint + types + tests) with tox:

tox            # all environments declared in tox.ini
tox -e py311   # one Python version
tox -e lint    # ruff + black --check
tox -e type    # mypy

Code style¶

We let tooling do the bikeshedding so reviewers can focus on the code:

Tool	Purpose	Config
black	Code formatter (line length 100)	`pyproject.toml → [tool.black]`
ruff	Linter + import sorter	`pyproject.toml → [tool.ruff]`
mypy	Static type checker (strict)	`pyproject.toml → [tool.mypy]`

Run them all locally before pushing:

black .
ruff check . --fix
mypy

A few conventions on top of the tooling:

Type-hint everything. mypy is in strict mode; new code without hints will fail CI.
Docstrings are NumPy-style (parsed by sphinx.ext.napoleon). Every public function, class, and module gets one.
Tests live in tests/, mirror the package layout, and use pytest’s function-style API. No unittest.TestCase classes.
No commented-out code in commits. Delete it; git remembers.

Building the documentation¶

Install the docs toolchain and run an autobuild server:

pip install -e ".[docs]"
sphinx-autobuild docs docs/_build/html

The site will be served at http://127.0.0.1:8000 and live-reload on every save. For a single one-shot build:

cd docs
make html         # Linux / macOS
.\make.bat html   # Windows

Submitting a pull request¶

Fork the repository and create a feature branch from main:
```
git checkout -b feat/short-descriptive-name
```
Make your changes in small, focused commits.
Add or update tests that exercise the change. PRs without tests for new behaviour are unlikely to be merged.
Update CHANGELOG.md under the [Unreleased] section.
Update documentation if you changed user-facing behaviour.

Run the full local check before pushing:

black . && ruff check . && mypy && pytest

Open the pull request against main. Fill in the PR template — what changes, why, and how you tested it.
Respond to review feedback. Pushes to your branch update the PR automatically; we’ll squash on merge.

Commit message style¶

We use Conventional Commits loosely. Examples:

feat(strategies): add Haar-random unitary strategy
fix(assertions): correct phase handling in assert_state_close
docs: clarify --qtest-seed semantics
chore(ci): bump actions/checkout to v4

This isn’t strictly enforced, but it makes the changelog easier to write at release time.

Reporting bugs¶

A great bug report has:

A short, descriptive title.
The qtest version (pip show qtest), Python version, and OS.
A minimal reproducer — the smallest possible test that triggers the bug. If the bug surfaces via a Hypothesis property, paste the shrunk blob Hypothesis prints.
What you expected to happen, and what actually happened.
The full traceback (not a screenshot).

Open the issue at https://github.com/metin-5115/qtest/issues.

Proposing features¶

Open an issue before writing significant code. We’d rather discuss design up front than ask you to rework a finished PR. A good feature proposal includes:

The problem you’re trying to solve, ideally with a concrete user-side example.
The API you have in mind (a snippet of the calling code is worth pages of prose).
Alternatives you considered and why you rejected them.

Security issues¶

Do not file security issues in the public issue tracker. See SECURITY.md for the disclosure process.

Thanks again for contributing to qtest!