diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3c231295f4..f6a70be8b6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -19,8 +19,6 @@ This checklist serves as a reminder of a couple of things that ensure your pull - [ ] The pull request only contains commits that are focused and relevant to this change. - [ ] I have added appropriate tests that cover the new/changed functionality. - [ ] I have updated the documentation to reflect these changes. -- [ ] I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals. -- [ ] I have added migration instructions to the upgrade guide (if needed). - [ ] The changes follow the project's style guidelines and introduce no new warnings. - [ ] The changes are fully tested and pass the CI checks. - [ ] I have reviewed my own code changes. diff --git a/.github/workflows/templating.yml b/.github/workflows/templating.yml index c88ed3eeb5..4a662ea27b 100644 --- a/.github/workflows/templating.yml +++ b/.github/workflows/templating.yml @@ -31,7 +31,7 @@ jobs: private-key: ${{ secrets.APP_PRIVATE_KEY }} permission-contents: write # Needed to push the templating branch permission-pull-requests: write # Needed to open the templating pull request - - uses: munich-quantum-toolkit/templates@93e56d3f8ad374d6bef4e57591a02bb5c6c03675 # v1.5.3 + - uses: munich-quantum-toolkit/templates@377a3dcd360ed3e4d879901dbda7d21e889f435b # main with: token: ${{ steps.create-token.outputs.token }} name: Core diff --git a/AGENTS.md b/AGENTS.md index d04ec1e724..978329abbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,9 +59,10 @@ Use relevant sections of the [development policy](docs/development.md) and the scoped workarounds with a technical reason, reproducer, and removal condition. - Follow the [release documentation policy](docs/development.md#release-documentation). - Record notable changes under Unreleased. Fold refinements to never-released - functionality into its feature entry; document migrations from released APIs, - not intermediate unreleased designs. + Describe user-facing changes and required migrations in PR descriptions. Do + not change `CHANGELOG.md` or `UPGRADING.md` except in release-preparation PRs + or when explicitly asked. Document migrations from released APIs, not + intermediate unreleased designs. - Changelog entries name the PR and every contributing author, for example `([#123]) ([**@username**])`, with link definitions at the bottom. - Never commit or print secrets or personal data. Use documented environment diff --git a/CHANGELOG.md b/CHANGELOG.md index f089464d0b..79c6fb9178 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,18 +8,6 @@ The format is based on a mixture of [Keep a Changelog] and [Common Changelog]. This project adheres to [Semantic Versioning], with the exception that minor releases may include breaking changes. -## [Unreleased] - -- ⚡ Speed up qubit placement and routing. Skip layout search for flat programs - whose initial qubit placement already satisfies the target topology. Place - disjoint interaction paths along connected target sites to avoid needless - routing SWAPs. ([#2544], [#2547]) ([**@burgholzer**]) - -- ✨ Optimize constant two-qubit blocks before placement and during native - synthesis. Remove cancelled interactions before routing and preserve cheaper - native operations in both target compilation and synthesis. Avoid redundant - cleanup in both target pipelines. ([#2537]) ([**@burgholzer**]) - ## [4.0.0] - 2026-09-11 ### MQT Core 4: a compiler foundation built on MLIR and LLVM @@ -1096,7 +1084,6 @@ for previous changelogs._ -[unreleased]: https://github.com/munich-quantum-toolkit/core/compare/v4.0.0...HEAD [4.0.0]: https://github.com/munich-quantum-toolkit/core/releases/tag/v4.0.0 [3.10.0]: https://github.com/munich-quantum-toolkit/core/releases/tag/v3.10.0 [3.9.2]: https://github.com/munich-quantum-toolkit/core/releases/tag/v3.9.2 @@ -1124,10 +1111,7 @@ for previous changelogs._ -[#2547]: https://github.com/munich-quantum-toolkit/core/pull/2547 -[#2544]: https://github.com/munich-quantum-toolkit/core/pull/2544 [#2538]: https://github.com/munich-quantum-toolkit/core/pull/2538 -[#2537]: https://github.com/munich-quantum-toolkit/core/pull/2537 [#2535]: https://github.com/munich-quantum-toolkit/core/pull/2535 [#2531]: https://github.com/munich-quantum-toolkit/core/pull/2531 [#2526]: https://github.com/munich-quantum-toolkit/core/pull/2526 diff --git a/UPGRADING.md b/UPGRADING.md index 62c30f8c62..de7767cb07 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -4,8 +4,6 @@ This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](CHANGELOG.md). -## [Unreleased] - ## [4.0.0] ### Migrating from MQT Core 3 to 4 @@ -23,8 +21,9 @@ or stay on the v3 release series. The low-level DD and QDMI libraries remain available; their migration requirements depend on whether they consume classic circuits or operate directly on states, matrices, devices, and jobs. -The [v4 release overview](CHANGELOG.md#unreleased) describes the new compiler -capabilities. This guide explains how to adopt them in existing applications. +The [v4 release overview](CHANGELOG.md#400---2026-09-11) describes the new +compiler capabilities. This guide explains how to adopt them in existing +applications. This section describes changes since **v3.10.0**. When upgrading from an older version, also consult the intervening release sections for changes that affect @@ -1249,7 +1248,6 @@ It also requires the `uv` library version 0.5.20 or higher. -[unreleased]: https://github.com/munich-quantum-toolkit/core/compare/v4.0.0...HEAD [4.0.0]: https://github.com/munich-quantum-toolkit/core/compare/v3.10.0...v4.0.0 [3.10.0]: https://github.com/munich-quantum-toolkit/core/compare/v3.9.2...v3.10.0 [3.9.2]: https://github.com/munich-quantum-toolkit/core/compare/v3.9.1...v3.9.2 diff --git a/docs/contributing.md b/docs/contributing.md index ecfc95badb..723438909e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -72,8 +72,8 @@ Contributions that do not comply with these guidelines or violate our - 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 details, see +- Document new features. Describe user-facing changes and required migrations in + the PR description. 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. @@ -628,43 +628,24 @@ 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]. There are -the following categories: +These documents are maintained during +{ref}`release preparation `. You do not need to update +them manually in feature or fix PRs. Include user-facing effects, limitations, +and migration instructions in your PR description so maintainers can collect +that information during release preparation. Apply the relevant labels for +Release Drafter. -- {code}`Added` for new features. -- {code}`Changed` for changes in existing functionality. -- {code}`Deprecated` for soon-to-be removed features. -- {code}`Removed` for now removed features. -- {code}`Fixed` for any bug fixes. -- {code}`Security` in case of vulnerabilities. - -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"). -- A single PR may result in multiple changelog entries. -- 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 Core, 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-new-version)= ## Releasing a New Version When it is time to release a new version of MQT Core, create a PR that prepares the release. This PR should: +- prepare the changelog and upgrade guide from the Git history, merged PR + descriptions, the Release Drafter draft, and any existing Unreleased notes. + Use the commits included in the release, accounting for backports and changes + already published on maintenance branches, - 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, @@ -678,6 +659,36 @@ the release. This PR should: - if the upgrade guide contains a section relevant to the release, add a reference to it in the changelog. +The changelog format is based on a mixture of [Keep a Changelog] and +[Common Changelog]. There are the following categories: + +- {code}`Added` for new features. +- {code}`Changed` for changes in existing functionality. +- {code}`Deprecated` for soon-to-be removed features. +- {code}`Removed` for now removed features. +- {code}`Fixed` for any bug fixes. +- {code}`Security` in case of vulnerabilities. + +During release preparation, follow these guidelines: + +- Cover the user-facing changes included in the release. +- 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. +- Group related changes so users can find the workflows and subsystems they use. +- Each entry links to the PR and all contributing authors. The links are defined + in the PR and contributor link sections at the bottom of the file. + +AI tools may help draft release documentation from the release diff and merged +PRs. A maintainer must verify the draft against those sources, including its +claims, PR links, and contributor attribution, before accepting it. + +Collect migration instructions from PR descriptions in the upgrade guide. +Explain how users must adapt their usage of MQT Core, including replacements for +changed or removed APIs and any changes in semantics. Add context for +significant new workflows where it helps users. Verify migration examples +against the released and proposed APIs. + 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 diff --git a/docs/development.md b/docs/development.md index 8a3b015340..54ed6e2cc9 100644 --- a/docs/development.md +++ b/docs/development.md @@ -229,32 +229,45 @@ requested. ## Release documentation -Record notable user-facing changes in the current Unreleased section of -`CHANGELOG.md`, with PR references and all contributing human authors. Group -entries by user workflow and subsystem. Fold refinements to functionality that -has never shipped into its feature entry. After release, describe subsequent -changes relative to that published behavior. +Do not change `CHANGELOG.md` or `UPGRADING.md` except in release-preparation PRs +or when explicitly asked. Feature and fix PR descriptions must explain +user-facing changes, limitations, and required migrations, with relevant labels +for Release Drafter. + +During release preparation, record notable user-facing changes with PR +references and all contributing human authors. Group entries by user workflow +and subsystem. Fold refinements to functionality that has never shipped into its +feature entry. After release, describe subsequent changes relative to that +published behavior. Lead major architectural releases with the new program model, enabled workflows, and consequences for existing users before listing individual changes. Keep the release overview and migration paths visible from the README and documentation home page. Preserve PR and contributor references when regrouping entries. -Document breaking changes to released interfaces in both `CHANGELOG.md` and -`UPGRADING.md`. Give the replacement, changed semantics, or lack of a -replacement. Do not add migrations between intermediate unreleased APIs. -Preserve published release sections except when correcting a verified error. - -Before a release, reconcile the Git history, merged PRs, and existing entries. -Account for maintenance branches, backports, and frontports; merge dates alone -do not define what ships for the first time. Include relevant feature and fix -PRs, verify contributor attribution, and record why maintenance-only changes do -not need public entries. Check migration examples against the released and -proposed APIs, build the executable documentation, and check its links. - -Keep Unreleased until the final version and release date are set. Version tags -drive package metadata; do not edit generated version files to stage a release. -Release preparation does not itself publish a release. +Document breaking changes to released interfaces and migration instructions in +the PR that introduces them. Give the replacement, changed semantics, or lack of +a replacement. During release preparation, collect these instructions in +`UPGRADING.md` and summarize the changes in `CHANGELOG.md`. Do not add +migrations between intermediate unreleased APIs. Preserve published release +sections except when correcting a verified error. + +Before a release, prepare the changelog and upgrade guide from the Git history, +merged PR descriptions, the Release Drafter draft, and any existing Unreleased +notes. Account for maintenance branches, backports, and frontports; merge dates +alone do not define what ships for the first time. Include relevant feature and +fix PRs, verify contributor attribution, and record why maintenance-only changes +do not need public entries. AI tools may help draft entries, but a maintainer +must verify their claims, PR links, and attribution against the release diff and +merged PRs before accepting the draft. Check migration examples against the +released and proposed APIs, build the executable documentation, and check its +links. + +Between releases, `CHANGELOG.md` and `UPGRADING.md` contain only published +releases. Create their next sections during release preparation and finalize the +version and release date before publishing. Version tags drive package metadata; +do not edit generated version files to stage a release. Release preparation does +not itself publish a release. ## Documentation validation