From 6cf0b5e48ed0ea837228a6cb1f429da6c04ac683 Mon Sep 17 00:00:00 2001 From: "mqt-app[bot]" <219534693+mqt-app[bot]@users.noreply.github.com> Date: Wed, 4 Mar 2026 10:47:42 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Update=20templated=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/release-drafter.yml | 4 ++ .github/renovate.json5 | 34 +++++++++++- docs/contributing.md | 72 ++++++++++++++++++++----- docs/installation.md | 103 ++++++++++++++++++++++++++++++++++++ docs/tooling.md | 82 ++++++++++++++++++++++++++++ 5 files changed, 281 insertions(+), 14 deletions(-) create mode 100644 docs/tooling.md diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 9e7070b..e120465 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -35,6 +35,10 @@ categories: - "submodules" change-template: "- $TITLE ([#$NUMBER]($URL)) ([**@$AUTHOR**](https://github.com/$AUTHOR))" change-title-escapes: '\<*_&' +exclude-labels: + - "skip-changelog" + - "backport" + - "release-prep" version-resolver: major: labels: diff --git a/.github/renovate.json5 b/.github/renovate.json5 index b0be0ff..5941cc5 100644 --- a/.github/renovate.json5 +++ b/.github/renovate.json5 @@ -1,5 +1,7 @@ { $schema: "https://docs.renovatebot.com/renovate-schema.json", + suppressNotifications: ["prEditedNotification"], + minimumReleaseAge: '7 days', extends: [ "config:recommended", ":gitSignOff", @@ -52,10 +54,38 @@ }, { description: "Group and automerge all patch updates", - groupName: "patch versions", - groupSlug: "all-patch", + groupName: "patch updates", matchUpdateTypes: ["patch"], + matchCurrentVersion: "!/^0\.0/", + commitMessagePrefix: "⬆\uFE0F\uD83E\uDE79", automerge: true }, + { + description: "Group and automerge all minor updates of stable dependencies (except our own packages)", + groupName: "minor stable updates", + matchUpdateTypes: ["minor"], + matchCurrentVersion: "!/^0\./", + matchPackageNames: [ + "!munich-quantum-toolkit/*", + "!munich-quantum-software/*", + ], + commitMessagePrefix: "⬆\uFE0F\uD83E\uDE79", + automerge: true + }, + { + description: 'Disable minimum release age checks for our own GitHub Actions', + matchManagers: ['github-actions'], + matchPackageNames: [ + 'munich-quantum-toolkit/*', + 'munich-quantum-software/*', + ], + minimumReleaseAge: null, + }, + { + description: 'Disable minimum release age checks for our own Python packages', + matchDatasources: ['pypi'], + matchPackageNames: ['mqt*'], + minimumReleaseAge: null, + } ] } diff --git a/docs/contributing.md b/docs/contributing.md index d644f4f..a169462 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,7 +4,7 @@ # Contributing Thank you for your interest in contributing to MQT core-plugins-catalyst! -This document outlines how to contribute and the development guidelines. +This document outlines the development guidelines and how to contribute. We use GitHub to [host code](https://github.com/munich-quantum-toolkit/core-plugins-catalyst), to [track issues and feature requests][issues], as well as accept [pull requests](https://github.com/munich-quantum-toolkit/core-plugins-catalyst/pulls). See for a general introduction to working with GitHub and contributing to projects. @@ -92,6 +92,44 @@ Please adhere to the following guidelines to help the project grow sustainably. - Do not squash commits locally; maintainers typically squash on merge. Avoid rebasing or force-pushing before reviews; you may rebase after addressing feedback if desired. +### Working with CodeRabbit + +We use [CodeRabbit](https://www.coderabbit.ai/) for automated code review on pull requests. +To get the most out of it and help the project maintain its high ambitions for code quality, please follow these practices: + +- **Draft PRs**: + CodeRabbit runs on every push to non-draft PRs. + If you are still experimenting, mark your PR as a draft so that the automated review only runs when you are ready for feedback. +- **Respond to comments**: + Do not simply resolve CodeRabbit's comments without answering them. + It learns from your replies and improves over time. + If a suggestion does not apply, take a moment to explain why in a reply. +- **Avoid multiple AI review bots**: + CodeRabbit performs significantly worse when other AI review bots (e.g., GitHub Copilot) are active on the same PR. + For the best results, do not tag Copilot unless you have already iterated with CodeRabbit and want an extra pass. +- **Engage CodeRabbit in discussions**: + When team members are discussing code in PR comments, CodeRabbit stays silent by default. + Tag {code}`@coderabbitai` to engage it in the conversation and get its feedback on the specific points being discussed. + In particular, when you tag another person in a comment, ensure to also tag CodeRabbit. + Otherwise, you will just get an automatic "It seems like the humans are having a chat" response from CodeRabbit anyway, which does not add much value. +- **Let CodeRabbit resolve comments**: + Wait until after the next push before considering resolving CodeRabbit's comments manually. + CodeRabbit will automatically resolve comments that it thinks have been addressed by your changes. + Sometimes, it gets stuck, at which point you may resolve it manually. +- **Manual review on drafts**: + You can trigger a full review on a draft PR by commenting with {code}`@coderabbitai full review`. +- **Continuing after reviews are paused**: + CodeRabbit has a default threshold for the number of reviews it performs on a PR before pausing further reviews to avoid spamming. + If you want to resume reviews, you can ask CodeRabbit to resume by commenting with {code}`@coderabbitai resume`. + Note that this will not trigger a review immediately; it will just allow CodeRabbit to perform reviews on the next push or manual trigger. + +### Use of AI and LLMs + +Contributions may be prepared with the help of AI or LLM tools. +However, [AI Slop](https://en.wikipedia.org/wiki/AI_slop)—generic, low-value, or clearly machine-generated content that does not meet our standards for clarity, accuracy, or usefulness—is not acceptable. +Ensure that all text, code, and documentation you submit are accurate, relevant, and consistent with the project's style and guidelines. +Please be mindful of the maintainers' time and consider the impact of your contributions on the project's long-term success. + ## Get Started 🎉 Ready to contribute? @@ -110,9 +148,9 @@ As of August 2025, our CI pipeline on GitHub continuously tests the library acro - {code}`ubuntu-24.04`: {code}`Release` and {code}`Debug` builds using {code}`gcc` - {code}`ubuntu-24.04-arm`: {code}`Release` build using {code}`gcc` +- {code}`macos-15`: {code}`Release` and {code}`Debug` builds using {code}`AppleClang` - {code}`macos-15-intel`: {code}`Release` build using {code}`AppleClang` -- {code}`macos-14`: {code}`Release` and {code}`Debug` builds using {code}`AppleClang` -- {code}`windows-2022`: {code}`Release` and {code}`Debug` builds using {code}`msvc` +- {code}`windows-2025`: {code}`Release` and {code}`Debug` builds using {code}`msvc` - {code}`windows-11-arm`: {code}`Release` build using {code}`msvc` To access the latest build logs, visit the [GitHub Actions page](https://github.com/munich-quantum-toolkit/core-plugins-catalyst/actions/workflows/ci.yml). @@ -253,14 +291,14 @@ See {ref}`working-on-documentation` for more information on how to build the doc ## Working on the Python Package -We use [{code}`pybind11`](https://pybind11.readthedocs.io/en/stable) to expose large parts of the C++ core library to Python. +We use [{code}`nanobind`](https://nanobind.readthedocs.io/) to expose large parts of the C++ core library to Python. This allows us to keep the performance-critical parts of the code in C++ while providing a convenient interface for Python users. All code related to C++-Python bindings is contained in the {code}`bindings` directory. :::{tip} To build only the Python bindings, pass {code}`-DBUILD_MQT_CORE-PLUGINS-CATALYST_BINDINGS=ON` to the CMake configure step. -CMake will then try to find Python and the necessary dependencies ({code}`pybind11`) on your system and configure the respective targets. +CMake will then try to find Python and the necessary dependencies ({code}`nanobind`) on your system and configure the respective targets. In [CLion][clion], you can enable an option to pass the current Python interpreter to CMake. Go to {code}`Preferences` -> {code}`Build, Execution, Deployment` -> {code}`CMake` -> {code}`Python Integration` and check the box {code}`Pass Python Interpreter to CMake`. Alternatively, you can pass {code}`-DPython_ROOT_DIR=` to the configure step to point CMake to a specific Python installation. @@ -275,12 +313,13 @@ We recommend using [{code}`nox`][nox] for development. {code}`nox` is a Python automation tool that allows you to define tasks in a {code}`noxfile.py` file and then run them with a single command. If you have not installed it yet, see our {ref}`installation guide for developers `. -We define four convenient {code}`nox` sessions in our {code}`noxfile.py`: +We define some convenient {code}`nox` sessions in our {code}`noxfile.py`: - {code}`tests` to run the Python tests - {code}`minimums` to run the Python tests with the minimum dependencies - {code}`lint` to run the Python code formatting and linting - {code}`docs` to build the documentation +- {code}`stubs` to regenerate the type stub files for the Python bindings These are explained in more detail in the following sections. @@ -301,7 +340,7 @@ We take extra care to install the project without build isolation so that rebuil If you only want to run the tests on a specific Python version, you can pass the desired Python version to the {code}`nox` command. ```console -$ nox -s tests-3.12 +$ nox -s tests-3.14 ``` :::{note} @@ -328,12 +367,12 @@ The Python code is formatted and linted using a collection of [{code}`pre-commit This collection includes - [ruff][ruff], an extremely fast Python linter and formatter written in Rust, and -- [mypy][mypy], a static type checker for Python code. +- [ty][ty], Astral's type checker for Python. The hooks can be installed by running the following command in the root directory: ```console -$ pre-commit install +$ prek install ``` This will install the hooks in the {code}`.git/hooks` directory of the repository. @@ -347,10 +386,10 @@ $ nox -s lint :::{note} -If you do not want to use {code}`nox`, you can also run the hooks manually by using {code}`pre-commit`. +If you do not want to use {code}`nox`, you can also run the hooks manually by using {code}`prek`. ```console -$ pre-commit run --all-files +$ prek run --all-files ``` ::: @@ -363,6 +402,13 @@ Every public function, class, and module should have a docstring that explains w We heavily rely on [type hints](https://docs.python.org/3/library/typing.html) to document the expected types of function arguments and return values. For the compiled parts of the code base, we provide type hints in the form of stub files in the {code}`python/mqt/core-plugins-catalyst` directory. +These stub files are auto-generated. +Do not edit them directly. +Instead, you can use the {code}`nox` session {code}`stubs` to regenerate them automatically. + +```console +nox -s stubs +``` The Python API documentation is integrated into the overall documentation that we host on ReadTheDocs using the [{code}`sphinx-autoapi`](https://sphinx-autoapi.readthedocs.io/en/latest/) extension for Sphinx. @@ -408,6 +454,7 @@ Here are some tips for finding the cause of certain failures: - If any of the {code}`CI / 🇨‌ Test` checks fail, this indicates build errors or test failures in the C++ part of the code base. Look through the respective logs on GitHub for any error or failure messages. + - If any of the {code}`CI / 🐍 Test` checks fail, this indicates build errors or test failures in the Python part of the code base. Look through the respective logs on GitHub for any error or failure messages. @@ -420,6 +467,7 @@ Here are some tips for finding the cause of certain failures: - If the {code}`pre-commit.ci` check fails, some of the {code}`pre-commit` checks failed and could not be fixed automatically by the _pre-commit.ci_ bot. The individual log messages frequently provide helpful suggestions on how to fix the warnings. + - If the {code}`docs/readthedocs.org:\*` check fails, the documentation could not be built properly. Inspect the corresponding log file for any errors. @@ -493,7 +541,7 @@ Afterward, navigate to the [Releases page](https://github.com/munich-quantum-too [clion]: https://www.jetbrains.com/clion/ -[mypy]: https://mypy-lang.org/ +[ty]: https://docs.astral.sh/ty/ [nox]: https://nox.thea.codes/en/stable/ [issues]: https://github.com/munich-quantum-toolkit/core-plugins-catalyst/issues [pipx]: https://pypa.github.io/pipx/ diff --git a/docs/installation.md b/docs/installation.md index 709ed2a..462604e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -334,6 +334,109 @@ For detailed guidelines and workflows, see {doc}`contributing`. $ prek install ``` +6. If you plan to develop for MQT core-plugins-catalyst, you will also need to install MLIR. + The section below describes how to do this. + +(setting-up-mlir)= + +## Setting Up MLIR + +MQT core-plugins-catalyst requires [MLIR](https://mlir.llvm.org/), which is part of the [LLVM](https://llvm.org/) project, to be available when building from source. +To successfully build MQT core-plugins-catalyst, you must make an installation of MLIR available to the C++ builds on your platform. + +We highly recommend using the prebuilt MLIR distribution provided by the [`portable-mlir-toolchain`] project. +These can be conveniently installed with the [`setup-mlir`] scripts as described below. + +### Downloading the MLIR Distribution + +The [`setup-mlir`] repository provides installation scripts for all supported operating systems. +You must pass the LLVM version (e.g., `22.1.0`) and the installation prefix (directory) where MLIR should be extracted. +The scripts download a platform-specific archive. +The only requirement is that the `tar` command is available on the system. + +::::{note} +:name: tar-requirement + +`tar` is included by default on Windows 10 and Windows 11. +On older Windows versions, you can install it, for example, via [Chocolatey](https://chocolatey.org/): `choco install tar`. +:::: + +::::{tab-set} +:::{tab-item} Linux and macOS + +Run the Bash script with the desired LLVM version and installation path: + +```console +$ curl -LsSf https://github.com/munich-quantum-software/setup-mlir/releases/latest/download/setup-mlir.sh | bash -s -- -v 22.1.0 -p /path/to/installation +``` + +Replace `/path/to/installation` with the directory where the LLVM distribution should be installed (e.g., `/opt/llvm-22.1.0`). + +::: +:::{tab-item} Windows + +Run the PowerShell script with the desired LLVM version and installation path: + +```console +$ powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://github.com/munich-quantum-software/setup-mlir/releases/latest/download/setup-mlir.ps1))) -llvm_version 22.1.0 -install_prefix \path\to\installation" +``` + +Replace `\path\to\installation` with the directory where the LLVM distribution should be installed (e.g., `C:\llvm-22.1.0`). +For debug builds on Windows, add the `-use_debug` flag to the script invocation. + +::: +:::: + +For supported LLVM versions, commit hashes, and other options, see the [`setup-mlir`] repository and its [`version-manifest.json`](https://github.com/munich-quantum-software/setup-mlir/blob/main/version-manifest.json). + +::::{note} +:name: mlir-build-note + +If you want to build MLIR from source, you can follow the instructions in the [`portable-mlir-toolchain`] repository. +This is not recommended unless you need a specific configuration that is not available in the prebuilt distributions, as building MLIR from source can be complex and time-consuming. +:::: + +### Making MLIR Available to the Build + +After installing MLIR, point the build system to it by setting the CMake variable {code}`MLIR_DIR` to the **CMake configuration directory** of the installation: + +```console +$ cmake -S . -B build -DMLIR_DIR=/path/to/installation/lib/cmake/mlir +``` + +Replace `/path/to/installation` with the actual path to the MLIR installation from the previous step. + +Alternatively, you can set the {code}`MLIR_DIR` environment variable to the same path before running CMake: + +::::{tab-set} +:::{tab-item} Linux and macOS + +```console +$ export MLIR_DIR=/path/to/installation/lib/cmake/mlir +``` + +::: +:::{tab-item} Windows (PowerShell) + +```console +$ $env:MLIR_DIR = "C:\path\to\installation\lib\cmake\mlir" +``` + +::: +:::: + +### Disabling MLIR + +If you do not need MLIR-based functionality, you can disable it by setting the {code}`BUILD_MQT_CORE-PLUGINS-CATALYST_MLIR` option to {code}`OFF`. +This disables all MLIR-related features in MQT core-plugins-catalyst and removes the dependency on MLIR. + +```console +$ cmake -S . -B build -DBUILD_MQT_CORE-PLUGINS-CATALYST_MLIR=OFF +``` + +[`setup-mlir`]: https://github.com/munich-quantum-software/setup-mlir/ +[`portable-mlir-toolchain`]: https://github.com/munich-quantum-software/portable-mlir-toolchain/ + [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html diff --git a/docs/tooling.md b/docs/tooling.md new file mode 100644 index 0000000..38ecd90 --- /dev/null +++ b/docs/tooling.md @@ -0,0 +1,82 @@ + + + +# Tooling + +This page summarizes the main tools, software, and standards used in MQT core-plugins-catalyst. +It serves as a quick reference for new contributors and users who want to understand the project's ecosystem. + +## C++ + +| Tool | Description | Links / Notes | +| ---------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- | +| **CMake** | Build system. | [Documentation](https://cmake.org/). | +| **clang-format** | Code formatter (LLVM style). | [Documentation](https://clang.llvm.org/docs/ClangFormat.html). Config: {code}`.clang-format` in project root. | +| **clang-tidy** | Static analysis and linting for C++. | [Documentation](https://clang.llvm.org/extra/clang-tidy/). Config: {code}`.clang-tidy` in project root. | +| **Doxygen** | C++ API documentation (comments). | [Documentation](https://www.doxygen.nl/). Rendered in Sphinx via [breathe](https://breathe.readthedocs.io/). | +| **GoogleTest** | C++ unit testing. | [Primer](https://google.github.io/googletest/primer.html). Tests in {code}`test/`; run via CTest. | + +## C++/Python Bindings and Packaging + +| Tool | Description | Links / Notes | +| --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| **nanobind** | C++/Python bindings (exposes C++ library to Python). | [Documentation](https://nanobind.readthedocs.io/). Bindings live in {code}`bindings`; stubs are auto-generated (see {doc}`contributing`). | +| **scikit-build-core** | Build backend for Python package. | [Documentation](https://scikit-build-core.readthedocs.io/en/latest/). | +| **cibuildwheel** | Builds wheels for all supported platforms and Python versions. | [Documentation](https://cibuildwheel.pypa.io/en/stable/). Configured in {code}`pyproject.toml`. | + +By using nanobind, we can take advantage of the [Stable ABI](https://docs.python.org/3/c-api/stable.html) for Python 3.12+. +This means that, starting from Python 3.12, we only need to build one wheel per platform, which can be used across all Python 3.12+ versions. +We still build separate wheels for older supported Python versions. + +Additionally, we support the free-threading version of Python that is no longer marked experimental as of Python 3.14. +The corresponding wheels are built separately since there is no stable ABI for free-threading Python yet. + +## MLIR + +| Tool | Description | Links / Notes | +| --------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| **MLIR** | Compiler infrastructure for building domain-specific compilers. | [Documentation](https://mlir.llvm.org/). We generally track the latest stable LLVM release. | +| **portable-mlir-toolchain** | Pre-built binaries for MLIR and LLVM on all supported platforms. | [Documentation](https://github.com/munich-quantum-software/portable-mlir-toolchain). | +| **setup-mlir** | Installation scripts and GitHub Action for installing pre-built MLIR toolchain. | [Documentation](https://github.com/munich-quantum-software/setup-mlir). | + +## Python + +| Tool | Description | Links / Notes | +| ---------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **uv** | Fast Python package and project manager (install, venv, dependencies). | [Documentation](https://docs.astral.sh/uv/). Recommended over {code}`pip` for installs and development. | +| **nox** | Task automation for tests, lint, docs, and other sessions defined in {code}`noxfile.py`. | [Documentation](https://nox.thea.codes/en/stable/). Run sessions with {code}`nox -s `. | +| **prek** | Runs hooks (formatting, linting) before each commit. | [Documentation](https://prek.j178.dev). Install and run via {code}`prek install`, {code}`prek run` (staged files), or {code}`prek run -a` (all files). | +| **ruff** | Linter and formatter for Python, written in Rust. | [Documentation](https://docs.astral.sh/ruff/). Used in prek and CI. | +| **ty** | Fast Python type checker and language server. | [Documentation](https://docs.astral.sh/ty/). | +| **pytest** | Testing framework for Python. | [Documentation](https://docs.pytest.org/). Run via {code}`nox -s tests` or {code}`uv run pytest`. | + +The project adheres to modern standards and practices. For the Python ecosystem, we make use of the following standards: + +| Standard | Description | Links / Notes | +| ----------- | --------------------------------------------------------------- | --------------------------------------------------- | +| **PEP 8** | Style guide for Python code. | [Documentation](https://peps.python.org/pep-0008/). | +| **PEP 518** | Specifying build system requirements in {code}`pyproject.toml`. | [Documentation](https://peps.python.org/pep-0518/). | +| **PEP 621** | Storing project metadata in {code}`pyproject.toml`. | [Documentation](https://peps.python.org/pep-0621/). | +| **PEP 639** | Standardized license metadata in {code}`pyproject.toml`. | [Documentation](https://peps.python.org/pep-0639/). | +| **PEP 723** | Inline script metadata for efficient script execution. | [Documentation](https://peps.python.org/pep-0723/). | +| **PEP 735** | Dependency groups in {code}`pyproject.toml`. | [Documentation](https://peps.python.org/pep-0735/). | + +## Documentation + +| Tool | Description | Links / Notes | +| ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- | +| **Sphinx** | Documentation generator. | [Documentation](https://www.sphinx-doc.org/). Docs source in {code}`docs/`. | +| **MyST** | Markdown flavor for Sphinx (used in docs). | [Documentation](https://myst-parser.readthedocs.io/). Enables rich Markdown in doc sources. | + +## CI and Quality + +| Tool | Description | Links / Notes | +| ------------------ | ------------------------------------------- | ---------------------------------------------------------------------- | +| **GitHub Actions** | CI workflows (build, test, lint, coverage). | [Reusable MQT Workflows] in {code}`.github/workflows/`; see [Actions]. | +| **Codecov** | Code coverage reporting. | [Codecov] for this repo. | +| **CodeRabbit** | Automated code review on PRs. | [CodeRabbit](https://www.coderabbit.ai/). See {doc}`contributing`. | +| **pre-commit.ci** | Runs pre-commit in CI and can auto-fix. | [pre-commit.ci](https://pre-commit.ci). | + +[Actions]: https://github.com/munich-quantum-toolkit/core-plugins-catalyst/actions +[Codecov]: https://codecov.io/gh/munich-quantum-toolkit/core-plugins-catalyst +[Reusable MQT Workflows]: https://github.com/munich-quantum-toolkit/workflows From 733f4f8fbfe6bcdb2ba506875e700ed7b51a6cb0 Mon Sep 17 00:00:00 2001 From: Daniel Haag <121057143+denialhaag@users.noreply.github.com> Date: Wed, 4 Mar 2026 11:48:36 +0100 Subject: [PATCH 2/2] Add link to tooling page --- docs/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.md b/docs/index.md index 910932a..0bf9bdb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,6 +27,7 @@ CHANGELOG :hidden: contributing +tooling support ```