📝 Prepare changelog and upgrade guide at release time

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

.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

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

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._
 
 <!-- Version links -->
 
-[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._
 
 <!-- PR links -->
 
-[#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

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.
 
 <!-- Version links -->
 
-[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

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 <CHANGELOG>` and an
 {doc}`upgrade guide <UPGRADING>`.
 
-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 <releasing-new-version>`. 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

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