diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ce303b9..17e2dcc 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -5,4 +5,4 @@ Thank you for your interest in contributing to MQT Debugger! An extensive contribution guide is available in our -[documentation](https://mqt.readthedocs.io/projects/debugger/en/latest/contributing.html). +[documentation](https://mqt.readthedocs.io/projects/debugger/en/stable/contributing.html). diff --git a/AGENTS.md b/AGENTS.md index b5fe0c1..aa01ec3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,6 +77,9 @@ `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 write tests that protect intended behavior or reproduce a concrete + regression. NEVER test provisional implementation choices that are not part of + the supported contract. - MUST place tests in the repository's corresponding test tree, organized by the component that owns the behavior. NEVER place tests or test fixtures in production source or tool directories. Reserve tool- or CLI-level subprocess @@ -85,6 +88,37 @@ build; avoid promoting an otherwise optional production tool into the default build solely for subprocess testing. - MUST follow existing code style by checking neighboring files for patterns. +- MUST write code comments, documentation, tests, changelog entries, and public + text for the final design. NEVER preserve prompts, review chronology, former + names, or abandoned approaches unless they remain necessary user-facing + context. +- MUST apply + [Orwell's six rules for writing](https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/) + to every category of prose, including reasoning, descriptions, commit + messages, documentation, docstrings, comments, test text, diagnostics, and + handoffs: + + 1. Do not use a familiar metaphor, simile, or other figure of speech. + 2. Use a short word when it has the same meaning as a long word. + 3. Remove every word that does not add meaning. + 4. Use active voice when possible. + 5. Use everyday English instead of a foreign phrase, scientific word, or + jargon term when this does not reduce precision. + 6. Break a rule before it makes the text unclear, incorrect, or needlessly + difficult to read. + +- MUST apply the relevant principles of + [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/): use + short, direct sentences; give each sentence one main idea; use one term for + one meaning; and use explicit nouns instead of vague pronouns. These are + mandatory style rules, not a claim of formal ASD-STE100 compliance. +- MUST base terminology and phrasing on existing usage in the repository and on + established precedents in the communities the repository draws from. Use the + established term that most precisely matches the concept. If communities use + different terms, explain the mapping once. NEVER invent synonyms for variety. +- MUST remove obsolete scaffolding and diagnostic suppressions before handoff. + Keep a workaround or suppression only when it is still necessary, scope it as + narrowly as possible, and document the technical reason. - AI assistance MUST be disclosed in the PR description. - Commit-level `Assisted-by: [Model Name] via [Tool Name]` trailers are recommended, not required. For example: diff --git a/docs/contributing.md b/docs/contributing.md index 5675f05..1c69c04 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -114,11 +114,11 @@ Claude picks up the same file. - 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. All checks must pass before merging. -- 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. +- Draft PRs may use a reduced test matrix, while all other CI checks still run. + Converting a draft to a regular PR triggers the full test matrix. +- After the full test matrix passes, request a review from a maintainer. If + unsure, ask in the 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. Do not close and reopen a new PR. Respond to comments to signal that you have addressed the feedback. Do not resolve review @@ -210,10 +210,8 @@ systems and compilers: To access the latest build logs, visit the [GitHub Actions page](https://github.com/munich-quantum-toolkit/debugger/actions/workflows/ci.yml). -Additionally, we regularly run extensive tests with an even wider matrix of -compilers and operating systems. We are not aware of any issues with other -compilers or operating systems. If you encounter any problems, please -[open an issue][issues] and let us know. +We are not aware of any issues with other compilers or operating systems. If you +encounter any problems, please [open an issue][issues] and let us know. ### Configure and Build