diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7771f356..98b58651 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,7 +6,7 @@ List any dependencies that are required for this change. Fixes #(issue) -## Checklist: +## Checklist + + +# MQT ProblemSolver + +## Python + +- Install package: `uv sync` +- Run tests: `uv run pytest` +- Nox test shortcuts: `uvx nox -s tests`, `uvx nox -s minimums` +- Python 3.14 variants: `uvx nox -s tests-3.14`, `uvx nox -s minimums-3.14` + +## Documentation + +- Sources: `docs/` +- Build docs locally: `uvx nox --non-interactive -s docs` +- Link check: `uvx nox -s docs -- -b linkcheck` + +## Tech Stack + +### General + +- `prek` for pre-commit hooks + +### Python + +- Python 3.10+ +- `uv` for installation, packaging, and tooling +- `ruff` for formatting/linting (configured in `pyproject.toml`) +- `ty` for type checking +- `pytest` for unit tests (located in `test/python/`) +- `nox` for task orchestration (tests, linting, docs) + +### Documentation + +- `sphinx` +- MyST (Markdown) +- Furo theme + +## Development Guidelines + +### 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). + All hooks must pass before submitting. +- 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 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). + +## Self-Review Checklist + +- Did `uvx nox -s lint` pass without errors? +- Are all changes covered by at least one automated test? diff --git a/docs/ai_usage.md b/docs/ai_usage.md new file mode 100644 index 00000000..4a314767 --- /dev/null +++ b/docs/ai_usage.md @@ -0,0 +1,113 @@ + + + +# 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. + +This guide outlines our policy on AI-assisted contributions to ensure code quality, maintainability, and legal compliance. + +## Core Principles + +### 1. You are Responsible + +**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: + +- 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. +- 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. + +### 2. Human in the Loop + +> **Autonomous contributions from AI agents are not allowed.** + +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. + +### 3. Communication + +**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"). +Phrase your communications in your own words. +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. + +**We encourage you to disclose any AI assistance.** +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. + +### 5. Licensing and Copyright + +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/problemsolver/blob/main/LICENSE.md). + +## Extractive Contributions + +Processing pull requests and comments for MQT ProblemSolver 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. +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. + +## 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. + +## 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. + +--- + +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. + +[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 +[LLVM]: https://github.com/llvm/llvm-project/blob/9b6391f9c439c9926e8587b7b940e9a1e98a7819/llvm/docs/AIToolPolicy.md +[fedora]: https://communityblog.fedoraproject.org/council-policy-proposal-policy-on-ai-assisted-contributions/ +[cca]: https://creativecommons.org/licenses/by/4.0/ diff --git a/docs/contributing.md b/docs/contributing.md index d8071bb0..5131b677 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -55,6 +55,7 @@ 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. ### Core Guidelines @@ -71,6 +72,15 @@ Please adhere to the following guidelines to help the project grow sustainably. - Follow the project's coding standards and conventions. - 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. + +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**. +We require disclosure of AI tool usage in your PR description. + ### Pull Request Workflow - Create PRs early. @@ -86,6 +96,12 @@ Please adhere to the following guidelines to help the project grow sustainably. 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. + 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. @@ -93,8 +109,15 @@ Please adhere to the following guidelines to help the project grow sustainably. ### 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. + 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. @@ -121,13 +144,6 @@ To get the most out of it and help the project maintain its high ambitions for c 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? diff --git a/docs/index.md b/docs/index.md index 0d4cc7cb..b0e4a2a4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -232,6 +232,7 @@ references :maxdepth: 1 contributing +ai_usage tooling support ```