Contributing#

Thank you for considering a contribution to Deltakit! We accept many types of contributions (most of which don’t even require writing code!) from anyone.

Types of Contributions#

Issues#

Bug reports#

We define a “bug” as a discrepancy between documented and actual behaviour or an inaccurate error message. (If it’s not a “bug”, see Enhancement Requests.) First, check to see if the bug has already been reported on the issue tracker. If so, leave a comment; if not, create a new bug report.

Enhancement Requests#

Other requests (besides bug reports) are also welcome! For instance, if the documentation needs improvement, if you disagree with documented behaviour, or if you are asking for a new feature, we’d appreciate your thoughts. First, check to see if a similar request already has an open issue. If so, leave a comment; if not, create a new request.

Issue Participation#

Posting an issue is the much-appreciated first step, but there’s lots more to do. Can you try reproducing a bug or finding out more about why it occurs? Can you help us reach consensus on the appropriate action to take to fix a bug or respond to a request? We welcome constructive participation in issues that look interesting to you.

Pull Requests#

Bug Fixes#

Known bugs can be found on the issue tracker. After reading the bug report carefully and reaching consensus on the appropriate fix, feel free to open a PR with the agreed-upon fix.

Enhancements#

Existing enhancement request can be found on the issue tracker. After reading the request carefully and reaching consensus on the appropriate action, feel free to open a PR with a fix. Note that many enhancements don’t require writing any code - documentation improvements are also appreciated!

PR Review#

All PRs need review before they can be merged. Please share your expertise in PRs that are up your alley.

Other#

Ask / Answer Questions#

Have a question about usage? Knowledgeable about our software and want to share your expertise? Please ask and answer usage questions on our Q&A Discussion.

Social Media / Graphic Design / Fundraising#

We don’t currently have recommendations about these types of contributions, but if you have ideas, please contact us.

Procedures#

Workflow#

For introductory information about contributing to open source (e.g. using GitHub, git), please see the Scientific Python Contributor Guide.

Development Environment and Common Tasks#

We recommend that contributors use pixi to manage their development environment and run tasks.

After cloning the repository and installing pixi, navigate to the root directory of the repository in a terminal and install dependencies with pixi install. pixi shell activates a development virtual environment with editable installs of Deltakit packages so you can make changes and interact with the modified code. To deactivate the environment, run exit.

Linux/macOS users…

Depending on system settings, you may experience a Too many open files (os error 24) at path... error. This is known issue that can easily be resolved by increasing the maximum number of open file descriptors; e.g., ulimit -n 512.

Conda users…

We suggest deactivating any conda environments before using pixi. If the conda base environment activates by default whenever a terminal session is opened, you can turn it off with conda config --set auto_activate_base false.

IDE users…

This environment is also available in several popular IDEs. For instance, to set up the Python interpreter in VS Code, you can set the python.defaultInterpreterPath variable to "${workspaceFolder}/.pixi/envs/default/bin/python" in settings.json.

You can also perform important tasks with pixi run. For example:

For instance:

pixi run tests deltakit-circuit
pixi run lint deltakit-explorer
pixi run docs

pixi will automatically update or install the dependencies (pixi install) and perform the task as defined in pixi.toml. Tasks include:

  • lint <package>: run ruff check on a package

  • mypy <package>: run mypy on a package

  • tests <package>: run tests on a package

  • testmon: run only changed tests / tests of changed code (after complete initial run)

  • tests <package> --slow: run all tests on a package, including slow tests

  • docs: build documentation, serve documentation, and open in browser.

  • build_docs: build documentation (only)

  • licenses <package>: run pip-licenses to generate a list of PyPI dependency licenses

  • ochrona/pip-audit: check your installed environment for package versions with known security issues

  • bandit: perform static code analysis for security concerns with bandit

  • check_pyproject <package>: to validate pyproject.toml

  • check_workflows: to validate GHA workflows

  • build <package>: build wheels and sdist to dist directory

  • spellcheck: to look for common misspellings in Python code

  • vale: to look for documentation style (including spelling) issues in documentation files

where <package> is the optional, hyphenated name of the desired Deltakit package.

pre-commit has been configured to perform several common tests before each commit. To enable pre-commit, run pre-commit install within a pixi shell (or pixi run pre-commit install otherwise).

Conda / Mamba / Poetry / Hatch / uv users…

You are welcome to manage your development environment using tools other than pixi.

# Create the virtual environment
conda env create -f environment.yml

# Activate the environment
conda activate deltakit-conda

# Run tests:
pytest

# Install deltakit and developer dependencies
poetry install --extras "dev"

# Run tests:
poetry run pytest

As shown, pytest is run outside of a poetry shell, hence the need for the poetry run prefix. If you have the poetry shell extension and activate it, the prefix is not needed.

# Create environment
hatch env create

# Activate shell
hatch shell

# Run tests:
pytest

# Install dependencies
uv sync --extra dev

# Run tests:
uv run pytest

As shown, pytest is run outside of a virtual environment, hence the need for the uv run prefix. If you use virtual environments with uv and activate the new virtual environment, the prefix is not needed.

There is not a designated task runner for use with tools other than pixi. Common commands besides pytest shown above are ruff check for linting, typos to find typos, mypy for static type checking, and pre-commit run -a to run several pre-commit checks. For additional commands, see the [tasks] section of pixi.ini.

Deltakit itself is compatible with Python 3.10+, but some of its dependencies currently require Python <3.14. If you run into difficulties associated with a Python version, consider configuring your package manager to use an earlier version of Python.

Code of Conduct#

When contributing, always follow our code of conduct.

Order of Operations#

Contributors without commit privileges are asked to submit or comment on an issue before submitting a pull request.

Issue / PR Titles / Commit Messages#

Our project uses semantic versioning. In particular, we use semantic release to automate our releases. Consequently, please format your issue/PR titles and commit messages according to the Conventional Commits specification with the following exceptions:

  • Use bug as the prefix for a bug-report issue; fix is reserved for PRs/commits that resolve a bug.

  • Use request as the prefix for a request; more descriptive prefixes (feat/perf) are used for PRs/commits.

Other commit types that we recognise include release (for work relating to release tooling and/or releases) and dev (for development work that doesn’t fit in another category), but typically these types will only be used by package maintainers.

Rebasing / Force-Pushing#

During PR review, please refrain from rebasing and force-pushing to your branch. If needed, feel free to add revert or merge commits; always use regular pushes. This ensures that reviewers can easily see what has changed since their last review. Once the PR has been approved but before it is merged, you’ll have the opportunity to do an interactive rebase (e.g. to improve commit history), or we can squash merge.

Inline Comment / Suggested Change Resolution#

PR contributors are asked to leave inline comments unresolved so reviewers can confirm that their comments have been addressed. (Reviewers, kindly resolve your own comments once you have checked them!) Exception: reviewers are encouraged to make use of the “Add a suggestion” feature, and contributors are encouraged to make use of the “Add suggestion to batch” and “Commit suggestions” features; these comments will automatically be resolved when the suggestions are committed.

License / Use of Artificial Intelligence#

Our project uses the Apache 2.0 license. Please ensure that your contributions are consistent with that license. If you’re unsure, please ask in an issue before posting content that may not be compatible with our project. Note that large language models (LLMs) may be trained on and can potentially reproduce content that is incompatible with our license. If an LLM or similar has influenced your contribution, please describe how so we can ensure that our project remains free of license-incompatible content.

Continuous Integration (CI) Usage#

Please use our CI services responsibly. Since CI re-runs on every push to a pull request branch, please avoid repeated pushes of small commits.

Minimum Supported Dependencies#

The project follows SPEC 0. Roughly, this means that we will support Python versions for three years and other core dependencies for two years.

Decision Making / Governance#

Decisions are made by consensus of participants in a GitHub issue or PR. In case of disagreement, code owners have final authority.

Code Formatting / Linting / Typing#

All packages except deltakit-decode use ruff format, all packages use ruff check to enforce linting rules, and all packages use mypy to enforce typing rules. See pyproject.toml for specific rules.

Release#

For more information about release processes, see the Deltakit release procedure.

Contributor License Agreement#

First-time contributors will be asked to agree to a CLA. This will be automated using a GitHub app shortly; in the meantime, please contact us.