📝 Update templated files

.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:

.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,
+    }
   ]
 }

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 <https://docs.github.com/en/get-started/quickstart> 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=<PATH_TO_PYTHON>` 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 <development-setup>`.
 
-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
 <!--- Links --->
 
 [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/

docs/index.md

@@ -27,6 +27,7 @@ CHANGELOG
 :hidden:
 
 contributing
+tooling
 support
 ```
 

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/
+
 <!-- Links -->
 
 [FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html