diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 57ab470fc..cf6bcc804 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,4 +4,5 @@ # Contributing Thank you for your interest in contributing to MQT Bench! -An extensive contribution guide is available in our [documentation](https://mqt.readthedocs.io/projects/bench/en/latest/contributing.html). +An extensive contribution guide is available in our +[documentation](https://mqt.readthedocs.io/projects/bench/en/latest/contributing.html). diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 1c4ec720d..313089cc8 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -9,14 +9,16 @@ Security updates are applied only to the most recent releases. ## Reporting a Vulnerability -To report vulnerabilities, you can privately report a potential security issue -via the GitHub security vulnerabilities feature. This can be done here: +To report vulnerabilities, +you can privately report a potential security issue via the GitHub security +vulnerabilities feature. +This can be done here: -https://github.com/munich-quantum-toolkit/bench/security/advisories + Please do **not** open a public issue about a potential security vulnerability. You can find more details on the security vulnerability feature in the GitHub documentation here: -https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability + diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index c201e5576..4015f13de 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -3,17 +3,23 @@ # Support -If you are stuck with a problem using MQT Bench or have questions, please get in touch at our [Issues] or [Discussions]. +If you are stuck with a problem using MQT Bench or have questions, +please get in touch at our [Issues] or [Discussions]. We'd love to help. You can save time by following this procedure when reporting a problem: - Do try to solve the problem on your own first. -- Search through past [Issues] and [Discussions] to see if someone else already had the same problem. -- Before filing a bug report, try to create a minimal reproducible example (MRE) that reproduces the problem. - It is much easier to identify the cause for the problem if a handful of lines suffice to show that something is not working. +- Search through past [Issues] and [Discussions] to see + if someone else already had the same problem. +- Before filing a bug report, + try to create a minimal reproducible example (MRE) + that reproduces the problem. + It is much easier to identify the cause for the problem + if a handful of lines suffice to show that something is not working. -You can also always reach us at [quantum.cda@xcit.tum.de](mailto:quantum.cda@xcit.tum.de). +You can also always reach us at +[quantum.cda@xcit.tum.de](mailto:quantum.cda@xcit.tum.de). [Issues]: https://github.com/munich-quantum-toolkit/bench/issues [Discussions]: https://github.com/munich-quantum-toolkit/bench/discussions diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7c3ec5e80..c55db4f60 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,7 +4,12 @@ Please include a summary of the change and, if applicable, which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. -Fixes #(issue) + + +Fixes #(issue) ## Checklist diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index ba89d41b3..db002ad51 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -33,7 +33,7 @@ categories: - "github-actions" - "pre-commit" - "submodules" -change-template: "- $TITLE ([#$NUMBER]($URL)) ([**@$AUTHOR**](https://github.com/$AUTHOR))" +change-template: "- $TITLE ([#$NUMBER]($URL)) (**@$AUTHOR**)" change-title-escapes: '\<*_&' exclude-labels: - "skip-changelog" diff --git a/AGENTS.md b/AGENTS.md index 825a4e6d8..e81b0d451 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,25 +42,43 @@ ### General - MUST run `uvx nox -s lint` after every batch of changes. - This runs the full `prek` hook set from `.pre-commit-config.yaml` (including `ruff`, `typos`, `ty`, formatting, and metadata checks). + This runs the full `prek` hook set from `.pre-commit-config.yaml` + (including `ruff`, `typos`, `ty`, formatting, and metadata checks). All hooks must pass before submitting. -- MUST add or update tests for every code change, even if not explicitly requested. +- MUST add or update tests for every code change, + even if not explicitly requested. - MUST follow existing code style by checking neighboring files for patterns. -- MUST update `CHANGELOG.md` and `UPGRADING.md` when changes are user-facing, breaking, or otherwise noteworthy. -- MUST include a commit footer attribution in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) if AI tools are used to prepare a commit. -- NEVER modify files that start with "This file has been generated from an external template. Please do not modify it directly." - These files are managed by [the MQT templates action](https://github.com/munich-quantum-toolkit/templates) and changes will be overwritten. +- MUST update `CHANGELOG.md` and `UPGRADING.md` when changes are user-facing, + breaking, or otherwise noteworthy. +- MUST include a commit footer attribution in the form + `Assisted-by: [Model Name] via [Tool Name]` (example: + `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) if AI tools are used to + prepare a commit. +- NEVER modify files that start with "This file has been generated from an + external template. + Please do not modify it directly." + These files are managed by + [the MQT templates action](https://github.com/munich-quantum-toolkit/templates) + and changes will be overwritten. - PREFER running targeted tests over the full test suite during development. ### Python - MUST use Google-style docstrings -- PREFER running a single Python version over the full test suite during development. -- PREFER fixing reported warnings over suppressing them (e.g., with `# noqa` comments for ruff); only add ignore rules when necessary and document why. -- PREFER fixing typing issues reported by `ty` before adding suppression comments (`# ty: ignore[code]`); suppressions are sometimes necessary for incompletely typed libraries (e.g., Qiskit). +- PREFER running a single Python version over the full test suite during + development. +- PREFER fixing reported warnings over suppressing them + (e.g., with `# noqa` comments for ruff); + only add ignore rules when necessary and document why. +- PREFER fixing typing issues reported by `ty` + before adding suppression comments + (`# ty: ignore[code]`); + suppressions are sometimes necessary for incompletely typed libraries + (e.g., Qiskit). ## Self-Review Checklist - Did `uvx nox -s lint` pass without errors? - Are all changes covered by at least one automated test? -- Are `CHANGELOG.md` and `UPGRADING.md` updated when changes are user-facing, breaking, or otherwise noteworthy? +- Are `CHANGELOG.md` and `UPGRADING.md` updated when changes are user-facing, + breaking, or otherwise noteworthy? diff --git a/docs/ai_usage.md b/docs/ai_usage.md index c0d8662c9..03ebc73fe 100644 --- a/docs/ai_usage.md +++ b/docs/ai_usage.md @@ -3,10 +3,15 @@ # AI Usage Guidelines -We acknowledge that AI tools (Large Language Models, code completion engines like GitHub Copilot, etc.) have become helpful assistants for many developers. -We allow the use of these tools to assist with contributions, provided that their use is transparent, responsible, and that a **human remains in the loop** at all times. +We acknowledge that AI tools +(Large Language Models, code completion engines like GitHub Copilot, etc.) +have become helpful assistants for many developers. +We allow the use of these tools to assist with contributions, +provided that their use is transparent, responsible, +and that a **human remains in the loop** at all times. -This guide outlines our policy on AI-assisted contributions to ensure code quality, maintainability, and legal compliance. +This guide outlines our policy on AI-assisted contributions to ensure code +quality, maintainability, and legal compliance. ## Core Principles @@ -14,13 +19,17 @@ This guide outlines our policy on AI-assisted contributions to ensure code quali **You are responsible for every line of code you submit.** -Regardless of whether code was written by you or generated by an AI tool, you are the author and are fully accountable for the contribution. You must: +Regardless of whether code was written by you or generated by an AI tool, +you are the author and are fully accountable for the contribution. +You must: - Fully understand the code you are submitting. -- Be able to explain the reasoning behind the code and how it interacts with the rest of the codebase. +- Be able to explain the reasoning behind the code + and how it interacts with the rest of the codebase. - Verify that the code is correct, efficient, and follows our coding standards. -**Do not blindly copy-paste AI-generated code.** If you cannot explain it, do not submit it. +**Do not blindly copy-paste AI-generated code.** +If you cannot explain it, do not submit it. ### 2. Human in the Loop @@ -29,82 +38,139 @@ Regardless of whether code was written by you or generated by an AI tool, you ar When using AI tools, you must be the driver. The AI is the assistant. -- **Review:** You must read and review all AI-generated code or text before submitting it. -- **Edit:** AI-generated code often requires significant editing to meet project standards and correctness. -- **Verify:** Ensure the code actually solves the problem and doesn't introduce subtle bugs or security vulnerabilities. +- **Review:** You must read and review all AI-generated code or text + before submitting it. +- **Edit:** AI-generated code often requires significant editing to meet project + standards and correctness. +- **Verify:** Ensure the code actually solves the problem + and doesn't introduce subtle bugs or security vulnerabilities. ### 3. Communication -**Do not use AI tools to generate issue descriptions, pull request comments, or code reviews.** +**Do not use AI tools to generate issue descriptions, pull request comments, or +code reviews.** We value your personal input and communication. -LLMs are notoriously unreliable and can produce "smart-sounding" but incorrect or irrelevant claims ("hallucinations"). +LLMs are notoriously unreliable and can produce "smart-sounding" but incorrect +or irrelevant claims ("hallucinations"). Phrase your communications in your own words. -It is more important that we can follow your reasoning than that the text sounds "perfect". +It is more important that we can follow your reasoning than +that the text sounds "perfect". ### 4. Transparency and Disclosure -Transparency helps the community understand the role of these tools and develop best practices. +Transparency helps the community understand the role of these tools +and develop best practices. **We encourage you to disclose any AI assistance.** -This helps us understand how these tools are being used and identify potential issues. +This helps us understand how these tools are being used +and identify potential issues. You can disclose this information in the following ways: -- **Commit Messages**: Add a trailer to your commit message in the form `Assisted-by: [Model Name] via [Tool Name]` (example: `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) -- **PR Description**: Mention the tool (name and version) and how it was used in the PR description. +- **Commit Messages**: Add a trailer to your commit message in the form + `Assisted-by: [Model Name] via [Tool Name]` (example: + `Assisted-by: Claude Sonnet 4.6 via GitHub Copilot`) +- **PR Description**: Mention the tool + (name and version) and how it was used in the PR description. ### 5. Licensing and Copyright -You are responsible for ensuring that your contribution does not violate any third-party licenses or copyrights. +You are responsible for ensuring +that your contribution does not violate any third-party licenses or copyrights. -- **Originality**: Your submission must be your own original work of authorship. -- **Training Data**: Be aware that some AI tools may generate code that is substantially similar to their training data. You must ensure that you have the right to contribute the generated code under [our license](https://github.com/munich-quantum-toolkit/bench/blob/main/LICENSE.md). +- **Originality**: + Your submission must be your own original work of authorship. +- **Training Data**: Be aware that some AI tools may generate code + that is substantially similar to their training data. + You must ensure that you have the right to contribute the generated code under + [our license](https://github.com/munich-quantum-toolkit/bench/blob/main/LICENSE). ## Extractive Contributions -Processing pull requests and comments for MQT Bench requires significant maintainer time and energy. -Sending unreviewed AI output to open-source projects shifts the burden of verifying correctness from the contributor to the maintainer. -We classify such contributions as "extractive" because they consume more community resources than they provide in value. - -Our **golden rule** is that a contribution should be valuable enough to justify the review effort. -Nadia Eghbal captures this concept in her book _[Working in Public](https://press.stripe.com/working-in-public)_: - -> "When attention is being appropriated, producers need to weigh the costs and benefits of the transaction. To assess whether the appropriation of attention is net-positive, it's useful to distinguish between _extractive_ and _non-extractive_ contributions. Extractive contributions are those where the marginal cost of reviewing and merging that contribution is greater than the marginal benefit to the project's producers. In the case of a code contribution, it might be a pull request that's too complex or unwieldy to review, given the potential upside." — Nadia Eghbal - -Before AI tools became widespread, open-source project maintainers would often review all changes sent to the project simply because submitting a pull request was a sign of interest from a potential long-term contributor. -However, AI tools now allow the rapid generation of large volumes of code, which can easily overwhelm maintainers if submitted without careful review. -Our policy exists to ensure that maintainer time is spent on high-quality interactions rather than debugging AI-generated code. +Processing pull requests and comments +for MQT Bench requires significant maintainer time and energy. +Sending unreviewed AI output to open-source projects shifts the burden of +verifying correctness from the contributor to the maintainer. +We classify such contributions as "extractive" +because they consume more community resources than they provide in value. + +Our **golden rule** is that a contribution should be valuable enough to justify +the review effort. +Nadia Eghbal captures this concept in her book +_[Working in Public](https://press.stripe.com/working-in-public)_: + +> "When attention is being appropriated, +> producers need to weigh the costs and benefits of the transaction. +> To assess whether the appropriation of attention is net-positive, +> it's useful to distinguish between _extractive_ +> and _non-extractive_ contributions. +> Extractive contributions are those where the marginal cost of reviewing +> and merging that contribution is greater than the marginal benefit to the +> project's producers. +> In the case of a code contribution, +> it might be a pull request that's too complex or unwieldy to review, +> given the potential upside." — Nadia Eghbal + +Before AI tools became widespread, +open-source project maintainers would often review all changes sent to the +project simply because submitting a pull request was a sign of interest from a +potential long-term contributor. +However, AI tools now allow the rapid generation of large volumes of code, +which can easily overwhelm maintainers if submitted without careful review. +Our policy exists to ensure +that maintainer time is spent on high-quality interactions rather than debugging +AI-generated code. ### Sustainable Open Source -The Munich Quantum Toolkit (MQT) is committed to remaining free, open-source, and permissively licensed. -We want to build a welcoming community where aspiring quantum software engineers can learn and grow. +The Munich Quantum Toolkit (MQT) is committed to remaining free, open-source, +and permissively licensed. +We want to build a welcoming community +where aspiring quantum software engineers can learn and grow. Reviewing contributions is a key part of this mentorship. -However, to keep the project sustainable, we must prioritize non-extractive contributions. -By thoroughly reviewing and understanding your AI-assisted code before submission, you ensure that your contribution is a net positive for the project. -This helps us maintain a healthy ecosystem where both the software and its contributors can thrive. +However, to keep the project sustainable, +we must prioritize non-extractive contributions. +By thoroughly reviewing and understanding your AI-assisted code +before submission, you ensure that your contribution is a net positive +for the project. +This helps us maintain a healthy ecosystem where both the software +and its contributors can thrive. ## Prohibited Uses -- **"Good First Issues"**: Do not use AI tools to solve issues labeled as "good first issue". These are intended as learning opportunities for new contributors. Automating them defeats the purpose. -- **Spam**: Do not use AI to generate low-quality or repetitive comments/reviews ("AI Slop"). -- **Unreviewed Code**: Submitting code that you, as a human, have not reviewed and tested yourself. +- **"Good First Issues"**: + Do not use AI tools to solve issues labeled as "good first issue". + These are intended as learning opportunities for new contributors. + Automating them defeats the purpose. +- **Spam**: Do not use AI to generate low-quality or repetitive comments/reviews + ("AI Slop"). +- **Unreviewed Code**: Submitting code that you, as a human, + have not reviewed and tested yourself. ## Summary -We want to foster a welcoming community where developers can learn and grow. AI tools can be great for productivity, but they should not replace critical thinking or the learning process. -If a maintainer judges that a contribution relies too heavily on unverified AI generation or lacks sufficient human understanding ("extractive contribution"), we may request that you revise it or close the PR. +We want to foster a welcoming community where developers can learn and grow. +AI tools can be great for productivity, +but they should not replace critical thinking or the learning process. +If a maintainer judges that a contribution relies too heavily on unverified AI +generation or lacks sufficient human understanding ("extractive contribution"), +we may request that you revise it or close the PR. --- -Parts of this guide were inspired by or adapted from the contribution guidelines of +Parts of this guide were inspired by +or adapted from the contribution guidelines of - [Astral], -- [Qiskit], -- [LLVM], including the sources therein, such as [Fedora Council Policy Proposal: Policy on AI-Assisted Contributions (fetched 2026-03-12)][fedora], which is licensed under the [Creative Commons Attribution 4.0 International License][cca]. - -with the help of Gemini 3 Pro (Preview). The links above serve as attribution. +- [Qiskit], and +- [LLVM], including the sources therein, such as + [Fedora Council Policy Proposal: Policy on AI-Assisted Contributions (fetched 2026-03-12)][fedora], + which is licensed under the + [Creative Commons Attribution 4.0 International License][cca], + +with the help of Gemini 3 Pro (Preview). +The links above serve as attribution. [Astral]: https://github.com/astral-sh/uv/blob/c89a78ec085077f6344b0439ddf07fdad7336310/CONTRIBUTING.md [Qiskit]: https://github.com/Qiskit/qiskit/blob/cd8701690723d3d9602fac63fe0bd7ea618799be/CONTRIBUTING.md#use-of-ai-tools diff --git a/docs/contributing.md b/docs/contributing.md index 593ba72d6..b11d5f2bb 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -6,8 +6,12 @@ Thank you for your interest in contributing to MQT Bench! This document outlines the development guidelines and how to contribute. -We use GitHub to [host code](https://github.com/munich-quantum-toolkit/bench), to [track issues and feature requests][issues], as well as accept [pull requests](https://github.com/munich-quantum-toolkit/bench/pulls). -See for a general introduction to working with GitHub and contributing to projects. +We use GitHub to +[host code](https://github.com/munich-quantum-toolkit/bench), to +[track issues and feature requests][issues], as well as accept +[pull requests](https://github.com/munich-quantum-toolkit/bench/pulls). +See +for a general introduction to working with GitHub and contributing to projects. ## Types of Contributions @@ -15,36 +19,45 @@ Pick the path that fits your time and interests: - 🐛 Report bugs: - Use the _🐛 Bug report_ template at . - Include steps to reproduce, expected vs. actual behavior, environment, and a minimal example. + Use the _🐛 Bug report_ template at + . + Include steps to reproduce, expected vs. actual behavior, environment, + and a minimal example. - 🛠️ Fix bugs: - Browse [issues][issues], especially those labeled "bug", "help wanted", or "good first issue". + Browse [issues][issues], especially those labeled "bug", "help wanted", + or "good first issue". Open a draft PR early to get feedback. - 💡 Propose features: - Use the _✨ Feature request_ template at . - Describe the motivation, alternatives considered, and (optionally) a small API sketch. + Use the _✨ Feature request_ template at + . + Describe the motivation, alternatives considered, + and (optionally) a small API sketch. - ✨ Implement features: Pick items labeled "feature" or "enhancement". - Coordinate in the issue first if the change is substantial; start with a draft PR. + Coordinate in the issue first if the change is substantial; + start with a draft PR. - 📝 Improve documentation: - Add or refine docstrings, tutorials, and examples; fix typos; clarify explanations. + Add or refine docstrings, tutorials, and examples; fix typos; + clarify explanations. Small documentation-only PRs are very welcome. - ⚡️ Performance and reliability: - Profile hot paths, add benchmarks, reduce allocations, deflake tests, and improve error messages. + Profile hot paths, add benchmarks, reduce allocations, deflake tests, + and improve error messages. - 📦 Packaging and tooling: - Improve build configuration, type hints/stubs, CI workflows, and platform wheels. + Improve build configuration, type hints/stubs, CI workflows, + and platform wheels. Incremental tooling fixes have a big impact. - 🙌 Community support: @@ -55,96 +68,135 @@ Pick the path that fits your time and interests: ## Guidelines Please adhere to the following guidelines to help the project grow sustainably. -Contributions that do not comply with these guidelines or violate our {doc}`AI Usage Guidelines ` may be rejected without further review. +Contributions that do not comply with these guidelines +or violate our {doc}`ai_usage` may be rejected without further review. ### Core Guidelines - ["Commit early and push often"](https://www.worklytics.co/blog/commit-early-push-often). -- Write meaningful commit messages, preferably using [gitmoji](https://gitmoji.dev) for additional context. +- Write meaningful commit messages, + preferably using [gitmoji](https://gitmoji.dev) for additional context. - Focus on a single feature or bug at a time and only touch relevant files. Split multiple features into separate contributions. - Add tests for new features to ensure they work as intended. - Document new features. - For user-facing changes, add a changelog entry; for breaking changes, update the upgrade guide. + For user-facing changes, add a changelog entry; for breaking changes, + update the upgrade guide. For details, see {ref}`maintaining-changelog-upgrade-guide`. - Add tests for bug fixes to demonstrate the fix. - Document your code thoroughly and ensure it is readable. -- Keep your code clean by removing debug statements, leftover comments, and unrelated code. +- Keep your code clean by removing debug statements, leftover comments, + and unrelated code. - Check your code for style and linting errors before committing. - Follow the project's coding standards and conventions. -- Be open to feedback and willing to make necessary changes based on code reviews. +- Be open to feedback and willing to make necessary changes based on code + reviews. ### AI-assisted contributions -We acknowledge the utility of AI-based coding assistants (e.g., GitHub Copilot, ChatGPT) in modern software development. -However, their use requires a high degree of responsibility and transparency to maintain code quality and licensing compliance. +We acknowledge the utility of AI-based coding agents +(e.g., Claude Code, OpenAI Codex, or GitHub Copilot) +in modern software development. +However, their use requires a high degree of responsibility +and transparency to maintain code quality and licensing compliance. -Please carefully read and follow our dedicated {doc}`AI Usage Guidelines ` before submitting any AI-assisted contribution. -In short: **You are responsible for every line of code you submit**, and a **human must always be in the loop**. +Please carefully read and follow our dedicated {doc}`ai_usage` +before submitting any AI-assisted contribution. +In short: **You are responsible for every line of code you submit**, +and a **human must always be in the loop**. We require disclosure of AI tool usage in your PR description. +If you use an agent, it will automatically read the provided {code}`AGENTS.md`, +which contains context and instructions to help the agent work on MQT Bench. +For Claude Code, create a symlink with {code}`ln -s AGENTS.md CLAUDE.md` +so Claude picks up the same file. + ### Pull Request Workflow - Create PRs early. Work-in-progress PRs are welcome; mark them as drafts on GitHub. -- Use a clear title, reference related issues by number, and describe the changes. +- Use a clear title, reference related issues by number, + and describe the changes. Follow the PR template; only omit the issue reference if not applicable. -- CI runs on all supported platforms and Python versions to build, test, format, and lint. +- CI runs on all supported platforms and Python versions to build, test, format, + and lint. All checks must pass before merging. -- When ready, convert the draft to a regular PR and request a review from a maintainer. +- When ready, convert the draft to a regular PR + and request a review from a maintainer. If unsure, ask in PR comments. - If you are a first-time contributor, mention a maintainer in a comment to request a review. -- If your PR gets a "Changes requested" review, address the feedback and push updates to the same branch. + If you are a first-time contributor, + mention a maintainer in a comment to request a review. +- If your PR gets a "Changes requested" review, + address the feedback and push updates to the same branch. Do not close and reopen a new PR. Respond to comments to signal that you have addressed the feedback. - Do not resolve review comments yourself; the reviewer will do so once satisfied. -- If the reviewer suggested changes with explicit code suggestions as part of the comments, apply these directly using the GitHub UI. - This attributes the changes to the reviewer and automatically resolves the respective comments (this is an exception to the rule above). - If there are multiple suggestions that you want to apply at once, you can batch them into a single commit. - Go to the "Files changed" tab of the PR, and then click "Add suggestion to batch" for each suggestion you want to include. + Do not resolve review comments yourself; + the reviewer will do so once satisfied. +- If the reviewer suggested changes with explicit code suggestions + as part of the comments, apply these directly using the GitHub UI. + This attributes the changes to the reviewer + and automatically resolves the respective comments + (this is an exception to the rule above). + If there are multiple suggestions that you want to apply at once, + you can batch them into a single commit. + Go to the "Files changed" tab of the PR, + and then click "Add suggestion to batch" + for each suggestion you want to include. Once you are done selecting suggestions, click "Commit suggestions". Only apply suggestions manually if using the GitHub UI is not feasible. - Re-request a review after pushing changes that address feedback. - 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. + 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. -We use this tool to ease the workload on our maintainers and to counteract the trend of sloppy AI-assisted contributions. -Note that having your PR reviewed by CodeRabbit does **not** count as an AI-assisted contribution for the purpose of the disclosure requirement mentioned above. +We often use [CodeRabbit](https://www.coderabbit.ai/) +for the initial review of PRs. +We use this tool to ease the workload on our maintainers +and to counteract the trend of sloppy AI-assisted contributions. + +Once your PR is ready, an initial review by CodeRabbit can be requested via +{code}`@coderabbitai full review`. +Just post this command as a PR comment on GitHub. +Any subsequent reviews can be requested via {code}`@coderabbitai review`. -To get the most out of it and help the project maintain its high ambitions for code quality, please follow these practices: +To get the most out of it and help the project maintain its high ambitions +for code quality, please follow these practices: -- **Review the review**: - Do not take CodeRabbit's suggestions as absolute truth. - LLMs can be overly defensive and conservative, leading to overcomplicated code. - Treat its comments as suggestions: consider them, but feel free to disagree and explain why. -- **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. +- **Review the review**: Do not take CodeRabbit's suggestions as absolute truth. + LLMs can be overly defensive and conservative, + leading to overcomplicated code. + Treat its comments as suggestions: consider them, + but feel free to disagree and explain why. - **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. + 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. + 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. + 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. + +Note that having your PR reviewed by CodeRabbit does **not** count +as an AI-assisted contribution +for the purpose of the disclosure requirement mentioned above. ## Get Started 🎉 @@ -155,15 +207,19 @@ We will guide you through the process. ## Installation -Check out our {ref}`installation guide for developers ` for instructions on how to set up your development environment. +Check out our {ref}`installation guide for developers ` +for instructions on how to set up your development environment. ## Working on the Package The package lives in the {code}`src/mqt/bench` directory. -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 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 some convenient {code}`nox` sessions in our {code}`noxfile.py`: @@ -176,114 +232,148 @@ These are explained in more detail in the following sections. ## Running the Tests -The Python code is tested by unit tests using the [{code}`pytest`](https://docs.pytest.org/en/latest/) framework. +The Python code is tested by unit tests using the +[{code}`pytest`](https://docs.pytest.org/en/latest/) framework. The corresponding test files can be found in the {code}`tests` directory. A {code}`nox` session is provided to conveniently run the Python tests. ```console -$ nox -s tests +nox -s tests ``` -This command automatically builds the project and runs the tests on all supported Python versions. -For each Python version, it will create a virtual environment (in the {code}`.nox` directory) and install the project into it. -We take extra care to install the project without build isolation so that rebuilds are typically very fast. +This command automatically builds the project +and runs the tests on all supported Python versions. +For each Python version, it will create a virtual environment +(in the {code}`.nox` directory) and install the project into it. +We take extra care to install the project without build isolation so +that rebuilds are typically very fast. -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. +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.14 +nox -s tests-3.14 ``` :::{note} -If you do not want to use {code}`nox`, you can also run the tests directly using {code}`pytest`. -This requires that you have the project and its test dependencies installed in your virtual environment (e.g., by running {code}`uv sync`). +If you do not want to use {code}`nox`, +you can also run the tests directly using {code}`pytest`. +This requires that you have the project +and its test dependencies installed in your virtual environment +(e.g., by running {code}`uv sync`). ```console -(.venv) $ pytest +pytest ``` ::: -We provide an additional nox session {code}`minimums` that makes use of {code}`uv`'s {code}`--resolution=lowest-direct` flag to install the lowest possible versions of the direct dependencies. -This ensures that the project can still be built and the tests pass with the minimum required versions of the dependencies. +We provide an additional nox session {code}`minimums` +that makes use of {code}`uv`'s {code}`--resolution=lowest-direct` flag to +install the lowest possible versions of the direct dependencies. +This ensures that the project can still be built +and the tests pass with the minimum required versions of the dependencies. ```console -$ nox -s minimums +nox -s minimums ``` ## Code Formatting and Linting -The Python code is formatted and linted using a collection of [{code}`pre-commit`][pre-commit] hooks. +The Python code is formatted and linted using a collection of pre-commit hooks. This collection includes -- [ruff][ruff], an extremely fast Python linter and formatter written in Rust, and +- [ruff][ruff], an extremely fast Python linter and formatter written in Rust, + and - [ty][ty], Astral's type checker for Python. -The hooks can be installed by running the following command in the root directory: +The hooks can be installed by running the following command in the root +directory: ```console -$ prek install +prek install ``` -This will install the hooks in the {code}`.git/hooks` directory of the repository. +This will install the hooks in the {code}`.git/hooks` directory of the +repository. The hooks will be executed whenever you commit changes. You can also run the {code}`nox` session {code}`lint` to run the hooks manually. ```console -$ nox -s lint +nox -s lint ``` :::{note} -If you do not want to use {code}`nox`, you can also run the hooks manually by using {code}`prek`. +If you do not want to use {code}`nox`, +you can also run the hooks manually by using [{code}`prek`][prek]. ```console -$ prek run --all-files +prek run --all-files ``` ::: ## Documentation -The Python code is documented using [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings). -Every public function, class, and module should have a docstring that explains what it does and how to use it. -{code}`ruff` will check for missing docstrings and will explicitly warn you if you forget to add one. +The Python code is documented using +[Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings). +Every public function, class, +and module should have a docstring that explains what it does +and how to use it. {code}`ruff` will check for missing docstrings +and will explicitly warn you if you forget to add one. -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. +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. -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. +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. (working-on-documentation)= ## Working on the Documentation -The documentation is written in [MyST](https://myst-parser.readthedocs.io/en/latest/index.html) (a flavor of Markdown) and built using [Sphinx](https://www.sphinx-doc.org/en/master/). +The documentation is written in +[MyST](https://myst-parser.readthedocs.io/en/latest/index.html) (a flavor of +Markdown) and built using [Sphinx](https://www.sphinx-doc.org/en/master/). The documentation source files can be found in the {code}`docs/` directory. -On top of the API documentation, we provide a set of tutorials and examples that demonstrate how to use the library. -These are written in Markdown using [myst-nb](https://myst-nb.readthedocs.io/en/latest/), which allows executing Python code blocks in the documentation. -The code blocks are executed during the documentation build process, and the output is included in the documentation. -This allows us to provide up-to-date examples and tutorials that are guaranteed to work with the latest version of the library. +On top of the API documentation, +we provide a set of tutorials and examples +that demonstrate how to use the library. +These are written in Markdown using +[myst-nb](https://myst-nb.readthedocs.io/en/latest/), which allows executing +Python code blocks in the documentation. +The code blocks are executed during the documentation build process, +and the output is included in the documentation. +This allows us to provide up-to-date examples and tutorials +that are guaranteed to work with the latest version of the library. You can build the documentation using the {code}`nox` session {code}`docs`. ```console -$ nox -s docs +nox -s docs ``` -This will install all dependencies for building the documentation in an isolated environment, build the Python package, and then build the documentation. +This will install all dependencies +for building the documentation in an isolated environment, +build the Python package, and then build the documentation. It will then host the documentation on a local web server for you to view. :::{note} -If you do not want to use {code}`nox`, you can also build the documentation directly using {code}`sphinx-build`. -This requires that you have the project and its documentation dependencies installed in your virtual environment (e.g., by running {code}`uv sync`). +If you do not want to use {code}`nox`, +you can also build the documentation directly using {code}`sphinx-build`. +This requires that you have the project +and its documentation dependencies installed in your virtual environment +(e.g., by running {code}`uv sync`). ```console -(.venv) $ sphinx-build -b html docs/ docs/_build +sphinx-build -b html docs/ docs/_build ``` The docs can then be found in the {code}`docs/_build` directory. @@ -295,24 +385,35 @@ The docs can then be found in the {code}`docs/_build` directory. If something goes wrong, the CI pipeline will notify you. 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. +- If any of the {code}`CI / 🐍 Test` checks fail, + this indicates build errors or test failures. Look through the respective logs on GitHub for any error or failure messages. -- If any of the {code}`codecov/\*` checks fail, this means that your changes are not appropriately covered by tests or that the overall project coverage decreased too much. +- If any of the {code}`codecov/\*` checks fail, + this means that your changes are not appropriately covered by tests or + that the overall project coverage decreased too much. Ensure that you include tests for all your changes in the PR. -- 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}`pre-commit.ci` check fails, + some of the {code}`prek` checks failed + and could not be fixed automatically by the + [pre-commit.ci](https://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. +- If the {code}`docs/readthedocs.org:\*` check fails, + the documentation could not be built properly. Inspect the corresponding log file for any errors. (maintaining-changelog-upgrade-guide)= ## Maintaining the Changelog and Upgrade Guide -MQT Bench adheres to [Semantic Versioning], with the exception that minor releases may include breaking changes. -To inform users about changes to the project, we maintain a {doc}`changelog ` and an {doc}`upgrade guide `. +MQT Bench adheres to [Semantic Versioning], +with the exception that minor releases may include breaking changes. +To inform users about changes to the project, +we maintain a {doc}`changelog ` +and an {doc}`upgrade guide `. If your PR includes noteworthy changes, please update the changelog. The format is based on a mixture of [Keep a Changelog] and [Common Changelog]. @@ -328,63 +429,86 @@ There are the following categories: When updating the changelog, follow these guidelines: - Add a changelog entry for every user-facing change in your PR. -- Write entries in the imperative mood (e.g., "Add support for X" or "Fix bug in Y"). +- Write entries in the imperative mood + (e.g., "Add support for X" or "Fix bug in Y"). - A single PR may result in multiple changelog entries. -- Entries in each category are sorted by merge time, with the latest PR appearing first. +- Entries in each category are sorted by merge time, + with the latest PR appearing first. - Each entry links to the PR and all contributing authors. The links are defined at the bottom of the file. - If this is your first contribution to this project, do not forget to add a link to your GitHub profile. - -If your PR introduces major or breaking changes, or if you think additional context would help users, please also add a section to the upgrade guide. -The upgrade guide is intended to provide a general overview of significant changes in a more descriptive and prose-oriented form than the changelog. -Use it to explain how users may need to adapt their usage of MQT Bench, highlight new workflows, or clarify the impact of important updates. -Feel free to write in a style that is helpful and accessible for users seeking to understand the broader implications of recent changes. + If this is your first contribution to this project, + do not forget to add a link to your GitHub profile. + +If your PR introduces major or breaking changes, +or if you think additional context would help users, +please also add a section to the upgrade guide. +The upgrade guide is intended to provide a general overview of significant +changes in a more descriptive and prose-oriented form than the changelog. +Use it to explain how users may need to adapt their usage of MQT Bench, +highlight new workflows, or clarify the impact of important updates. +Feel free to write in a style that is helpful and accessible +for users seeking to understand the broader implications of recent changes. ## Releasing a New Version -When it is time to release a new version of MQT Bench, create a PR that prepares the release. +When it is time to release a new version of MQT Bench, +create a PR that prepares the release. This PR should: - add new version titles in both the changelog and the upgrade guide, - add the release date to the changelog entry for the new version, - update the version links at the bottom of both files, -- review and streamline all changelog and upgrade guide entries for clarity and consistency, +- review and streamline all changelog and upgrade guide entries for clarity + and consistency, - ensure that all links (to PRs, authors, etc.) are defined and correct, -- double-check that the changelog comprehensively covers all changes since the last release and that nothing is missing, -- review the upgrade guide to ensure it covers all major or breaking changes and provides helpful context, and -- if the upgrade guide contains a section relevant to the release, add a reference to it in the changelog. - -Before merging the PR preparing the release, check the GitHub release draft generated by the Release Drafter for unlabelled PRs. -Unlabelled PRs would appear at the top of the release draft below the main heading. -If you missed updating labels before merging, you can still update them and re-run the Release Drafter afterward. +- double-check that the changelog comprehensively covers all changes + since the last release and that nothing is missing, +- review the upgrade guide to ensure it covers all major or breaking changes + and provides helpful context, and +- if the upgrade guide contains a section relevant to the release, + add a reference to it in the changelog. + +Before merging the PR preparing the release, +check the GitHub release draft generated by the Release Drafter +for unlabelled PRs. +Unlabelled PRs would appear at the top of the release draft below the main +heading. +If you missed updating labels before merging, +you can still update them and re-run the Release Drafter afterward. Furthermore, check whether the version number in the release draft is correct. -The version number in the release draft is dictated by the presence of certain labels on the PRs involved in a release. +The version number in the release draft is dictated by the presence of certain +labels on the PRs involved in a release. By default, a patch release will be created. -If any PR has the {code}`minor` or {code}`major` label, a minor or major release will be created, respectively. +If any PR has the {code}`minor` or {code}`major` label, +a minor or major release will be created, respectively. :::{note} -Sometimes, Dependabot or Renovate will tag a PR updating a dependency with a {code}`minor` or {code}`major` label because the dependency update itself is a minor or major release. -This does not mean that the dependency update itself is a breaking change for MQT Bench. -If you are sure that the dependency update does not introduce any breaking changes for MQT Bench, you can remove the {code}`minor` or {code}`major` label from the PR. -This will ensure that the respective PR does not influence the type of an upcoming release. +Sometimes, Dependabot or Renovate will tag a PR updating a dependency with a +{code}`minor` or {code}`major` label because the dependency update itself is a +minor or major release. +This does not mean that the dependency update itself is a breaking change +for MQT Bench. +If you are sure that the dependency update does not introduce any breaking +changes for MQT Bench, you can remove the {code}`minor` or {code}`major` +label from the PR. +This will ensure that the respective PR does not influence the type of an +upcoming release. ::: Once everything is in order, you can merge the PR preparing the release. -Afterward, navigate to the [Releases page](https://github.com/munich-quantum-toolkit/bench/releases) on GitHub, edit the release draft if necessary, and publish the release. +Afterward, navigate to the +[Releases page](https://github.com/munich-quantum-toolkit/bench/releases) on +GitHub, edit the release draft if necessary, and publish the release. -[clion]: https://www.jetbrains.com/clion/ -[ty]: https://docs.astral.sh/ty/ [nox]: https://nox.thea.codes/en/stable/ -[issues]: https://github.com/munich-quantum-toolkit/bench/issues -[pipx]: https://pypa.github.io/pipx/ -[pre-commit]: https://pre-commit.com/ +[prek]: https://prek.j178.dev [ruff]: https://docs.astral.sh/ruff/ -[uv]: https://docs.astral.sh/uv/ -[vscode]: https://code.visualstudio.com/ +[ty]: https://docs.astral.sh/ty/ +[issues]: https://github.com/munich-quantum-toolkit/bench/issues [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/ [Common Changelog]: https://common-changelog.org [Semantic Versioning]: https://semver.org/spec/v2.0.0.html diff --git a/docs/installation.md b/docs/installation.md index 27bdc09dc..f1da92785 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,34 +3,42 @@ # Installation -MQT Bench is a Python package available on [PyPI](https://pypi.org/project/mqt.bench/). -It can be installed on all major operating systems with all [officially supported Python versions](https://devguide.python.org/versions/). +MQT Bench is a Python package available on +[PyPI](https://pypi.org/project/mqt.bench/). +It can be installed on all major operating systems with all +[officially supported Python versions](https://devguide.python.org/versions/). :::::{tip} :name: uv-recommendation We recommend using [{code}`uv`][uv]. -It is a fast Python package and project manager by [Astral](https://astral.sh/) (creators of [{code}`ruff`][ruff]). -It can replace {code}`pip` and {code}`virtualenv`, automatically manages virtual environments, installs packages, and can install Python itself. +It is a fast Python package and project manager by [Astral](https://astral.sh/) +(creators of [{code}`ruff`][ruff]). +It can replace {code}`pip` and {code}`virtualenv`, +automatically manages virtual environments, installs packages, +and can install Python itself. It is significantly faster than {code}`pip`. If you do not have {code}`uv` installed, install it with: ::::{tab-set} -:::{tab-item} macOS and Linux + +:::{tab-item} Linux and macOS ```console -$ curl -LsSf https://astral.sh/uv/install.sh | sh +curl -LsSf https://astral.sh/uv/install.sh | sh ``` ::: -:::{tab-item} Windows + +:::{tab-item} Windows (PowerShell) ```console -$ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` ::: + :::: See the [uv documentation][uv] for more information. @@ -44,7 +52,7 @@ See the [uv documentation][uv] for more information. :sync: uv ```console -$ uv pip install mqt.bench +uv pip install mqt.bench ``` ::: @@ -53,23 +61,25 @@ $ uv pip install mqt.bench :sync: pip ```console -(.venv) $ python -m pip install mqt.bench +python -m pip install mqt.bench ``` ::: + :::: Verify the installation: ```console -(.venv) $ python -c "import mqt.bench; print(mqt.bench.__version__)" +python -c "import mqt.bench; print(mqt.bench.__version__)" ``` This prints the installed package version. ## Integrating MQT Bench into Your Project -To use the MQT Bench Python package in your project, add it as a dependency in your {code}`pyproject.toml` or {code}`setup.py`. +To use the MQT Bench Python package in your project, +add it as a dependency in your {code}`pyproject.toml` or {code}`setup.py`. This ensures the package is installed when your project is installed. ::::{tab-set} @@ -77,7 +87,7 @@ This ensures the package is installed when your project is installed. :::{tab-item} {code}`uv` _(recommended)_ ```console -$ uv add mqt.bench +uv add mqt.bench ``` ::: @@ -106,6 +116,7 @@ setup( ``` ::: + :::: (development-setup)= @@ -116,124 +127,142 @@ Set up a reproducible development environment for MQT Bench. This is the recommended starting point for both bug fixes and new features. For detailed guidelines and workflows, see {doc}`contributing`. -1. Get the code: +1. Get the code: + + ::::{tab-set} + + :::{tab-item} External Contribution + + If you do not have write access to the + [munich-quantum-toolkit/bench](https://github.com/munich-quantum-toolkit/bench) + repository, fork the repository on GitHub (see + ) and clone + your fork locally. + + ```console + git clone git@github.com:your_name_here/bench.git mqt-bench + ``` + + ::: - ::::{tab-set} - :::{tab-item} External Contribution - If you do not have write access to the [munich-quantum-toolkit/bench](https://github.com/munich-quantum-toolkit/bench) repository, fork the repository on GitHub (see ) and clone your fork locally. + :::{tab-item} Internal Contribution - ```console - $ git clone git@github.com:your_name_here/bench.git mqt-bench - ``` + If you have write access to the + [munich-quantum-toolkit/bench](https://github.com/munich-quantum-toolkit/bench) + repository, clone the repository locally. - ::: - :::{tab-item} Internal Contribution - If you have write access to the [munich-quantum-toolkit/bench](https://github.com/munich-quantum-toolkit/bench) repository, clone the repository locally. + ```console + git clone git@github.com/munich-quantum-toolkit/bench.git mqt-bench + ``` - ```console - $ git clone git@github.com/munich-quantum-toolkit/bench.git mqt-bench - ``` + ::: - ::: - :::: + :::: -2. Change into the project directory: +2. Change into the project directory: - ```console - $ cd mqt-bench - ``` + ```console + cd mqt-bench + ``` -3. Create a branch for local development: +3. Create a branch for local development: - ```console - $ git checkout -b name-of-your-bugfix-or-feature - ``` + ```console + git checkout -b name-of-your-bugfix-or-feature + ``` - Now you can make your changes locally. + Now you can make your changes locally. -4. Install the project and its development dependencies: +4. Install the project and its development dependencies: - We highly recommend using modern, fast tooling for the development workflow. - We recommend using [{code}`uv`][uv]. - If you don't have {code}`uv`, follow the installation instructions in the recommendation above (see {ref}`tip above `). - See the [uv documentation][uv] for more information. + We highly recommend using modern, fast tooling for the development workflow. + We recommend using [{code}`uv`][uv]. + If you don't have {code}`uv`, + follow the installation instructions in the recommendation above + (see {ref}`tip above `). + See the [uv documentation][uv] for more information. - ::::{tab-set} - :sync-group: installer + ::::{tab-set} + :sync-group: installer - :::{tab-item} {code}`uv` _(recommended)_ - :sync: uv - Install the project (including development dependencies) with [{code}`uv`][uv]: + :::{tab-item} {code}`uv` _(recommended)_ + :sync: uv - ```console - $ uv sync - ``` + Install the project (including development dependencies) with [{code}`uv`][uv]: - ::: - :::{tab-item} {code}`pip` - :sync: pip - If you really don't want to use [{code}`uv`][uv], you can install the project and the development dependencies into a virtual environment using {code}`pip`. + ```console + uv sync + ``` - ```console - $ python -m venv .venv - $ source ./.venv/bin/activate - (.venv) $ python -m pip install -U pip - (.venv) $ python -m pip install -e . --group dev - ``` + ::: - ::: - :::: + :::{tab-item} {code}`pip` + :sync: pip -5. Install pre-commit hooks to ensure code quality: + If you really don't want to use [{code}`uv`][uv], you can install the project + and the development dependencies into a virtual environment using + {code}`pip`. - The project uses [pre-commit] hooks for running linters and formatting tools on each commit. - These checks can be run manually via [{code}`nox`][nox], by running: + ```console + python -m venv .venv + source ./.venv/bin/activate + python -m pip install -U pip + python -m pip install -e . --group dev + ``` - ```console - $ nox -s lint - ``` + ::: - They can also be run automatically on every commit via [{code}`prek`][prek] (recommended). - To set this up, install {code}`prek`, e.g., via: + :::: - ::::{tab-set} - :::{tab-item} macOS and Linux +5. Install pre-commit hooks to ensure code quality: - ```console - $ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh - ``` + The project uses pre-commit hooks for running linters and formatting tools on each commit. + These checks can be run manually via [{code}`nox`][nox], by running: - ::: - :::{tab-item} Windows + ```console + nox -s lint + ``` - ```console - $ powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/latest/download/prek-installer.ps1 | iex" - ``` + They can also be run automatically on every commit via [{code}`prek`][prek] (recommended). To set + this up, install {code}`prek`, e.g., via: - ::: + ::::{tab-set} - :::{tab-item} {code}`uv` + :::{tab-item} Linux and macOS - ```console - $ uv tool install prek - ``` + ```console + curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh + ``` - ::: - :::: + ::: - Then run: + :::{tab-item} Windows (PowerShell) - ```console - $ prek install - ``` + ```console + powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/latest/download/prek-installer.ps1 | iex" + ``` + + ::: + + :::{tab-item} {code}`uv` + + ```console + uv tool install prek + ``` + + ::: + + :::: + + Then run: + + ```console + prek install + ``` -[FetchContent]: https://cmake.org/cmake/help/latest/module/FetchContent.html -[git-submodule]: https://git-scm.com/docs/git-submodule [nox]: https://nox.thea.codes/en/stable/ -[pipx]: https://pypa.github.io/pipx/ -[pre-commit]: https://pre-commit.com/ [prek]: https://prek.j178.dev -[ruff]: https://docs.astral.sh/ruff/ [uv]: https://docs.astral.sh/uv/ +[ruff]: https://docs.astral.sh/ruff/ diff --git a/docs/tooling.md b/docs/tooling.md index 663ea9d2f..4d6089752 100644 --- a/docs/tooling.md +++ b/docs/tooling.md @@ -3,8 +3,10 @@ # Tooling -This page summarizes the main tools, software, and standards used in MQT Bench. -It serves as a quick reference for new contributors and users who want to understand the project's ecosystem. +This page summarizes the main tools, software, +and standards used in MQT Bench. +It serves as a quick reference for new contributors +and users who want to understand the project's ecosystem. ## Python @@ -17,7 +19,8 @@ It serves as a quick reference for new contributors and users who want to unders | **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: +The project adheres to modern standards and practices. +For the Python ecosystem, we make use of the following standards: | Standard | Description | Links / Notes | | ----------- | --------------------------------------------------------------- | --------------------------------------------------- | @@ -41,8 +44,8 @@ The project adheres to modern standards and practices. For the Python ecosystem, | ------------------ | ------------------------------------------- | ---------------------------------------------------------------------- | | **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). | +| **CodeRabbit** | Initial PR reviews. | [CodeRabbit](https://www.coderabbit.ai/). See {doc}`contributing`. | +| **pre-commit.ci** | Runs pre-commit hooks in CI and auto-fixes. | [pre-commit.ci](https://pre-commit.ci). | [Actions]: https://github.com/munich-quantum-toolkit/bench/actions [Codecov]: https://codecov.io/gh/munich-quantum-toolkit/bench