From 07bf481ac733abd7d59c9170f016468cb2378931 Mon Sep 17 00:00:00 2001 From: Simon Hofmann Date: Sun, 13 Sep 2026 21:34:33 +0200 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9D=20Prepare=20changelogs=20durin?= =?UTF-8?q?g=20releases?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– *AI text below* πŸ€– Move changelog preparation out of feature and fix PRs. Remove the Unreleased section and its links while preserving published release notes. Keep migration instructions with the changes that introduce them. Regenerate contributor guidance and the PR checklist from templates#449, pin its source revision, and align Core's development and agent policies. Assisted-by: GPT-6 via Codex --- .github/pull_request_template.md | 1 - .github/workflows/templating.yml | 2 +- AGENTS.md | 6 ++--- CHANGELOG.md | 16 ------------- UPGRADING.md | 5 ++-- docs/contributing.md | 29 ++++++++++++++-------- docs/development.md | 41 ++++++++++++++++++++------------ 7 files changed, 52 insertions(+), 48 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3c231295f4..6fe2cd1289 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -19,7 +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. diff --git a/.github/workflows/templating.yml b/.github/workflows/templating.yml index c88ed3eeb5..b400cc6e46 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@5e5931c8c07cba504758b55ee8b6c4da6729f86c # templates#449 with: token: ${{ steps.create-token.outputs.token }} name: Core diff --git a/AGENTS.md b/AGENTS.md index d04ec1e724..6df683eadf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,9 +59,9 @@ 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 in PR descriptions. Prepare changelog entries + during release preparation; feature and fix PRs do not need them. 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..2754c103d3 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -23,8 +23,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 diff --git a/docs/contributing.md b/docs/contributing.md index ecfc95badb..d5756b842c 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -72,7 +72,7 @@ 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 +- Document new features. Describe user-facing changes in the PR description; for breaking changes, update the upgrade guide. For details, see {ref}`maintaining-changelog-upgrade-guide`. - Add tests for bug fixes to demonstrate the fix. @@ -628,9 +628,12 @@ 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: +Prepare the changelog in release-preparation PRs. Feature and fix PRs do not +need changelog entries. Describe their user-facing effects and limitations in +the PR description, and apply the relevant labels for Release Drafter. + +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. @@ -639,17 +642,19 @@ the following categories: - {code}`Fixed` for any bug fixes. - {code}`Security` in case of vulnerabilities. -When updating the changelog, follow these guidelines: +During release preparation, follow these guidelines: -- Add a changelog entry for every user-facing change in your PR. +- 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. -- Entries in each category are sorted by merge time, with the latest PR - appearing first. +- 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 - 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. + in the PR and contributor link sections at the bottom of the file. + +AI tools may help draft entries 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. 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 @@ -665,6 +670,10 @@ implications of recent changes. When it is time to release a new version of MQT Core, create a PR that prepares the release. This PR should: +- prepare changelog entries 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, diff --git a/docs/development.md b/docs/development.md index 8a3b015340..85d251536e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -229,32 +229,43 @@ 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. +Prepare `CHANGELOG.md` in release-preparation PRs. Feature and fix PRs do not +need changelog entries. Their descriptions must explain user-facing changes and +limitations, 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. +Document breaking changes to released interfaces in `UPGRADING.md` with the PR +that introduces them. Give the replacement, changed semantics, or lack of a +replacement. Summarize these changes in `CHANGELOG.md` during release +preparation. 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. +Before a release, prepare the changelog 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. 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. +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` contains only published releases. Create the +next section during release preparation and finalize its 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 From 4ffb43de2bd8c187fe5ed282ad3d2e4027bf194e Mon Sep 17 00:00:00 2001 From: Simon Hofmann Date: Sun, 13 Sep 2026 23:23:00 +0200 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D=20Defer=20upgrade=20guides=20t?= =?UTF-8?q?o=20release=20preparation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– *AI text below* πŸ€– Prepare the upgrade guide with the changelog at release time and keep migration instructions in feature PR descriptions. Remove its empty Unreleased section, regenerate shared guidance and the PR checklist, and update the template pin. Assisted-by: GPT-6 via Codex --- .github/pull_request_template.md | 1 - .github/workflows/templating.yml | 2 +- AGENTS.md | 7 ++--- UPGRADING.md | 3 --- docs/contributing.md | 38 +++++++++++++-------------- docs/development.md | 44 +++++++++++++++++--------------- 6 files changed, 46 insertions(+), 49 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6fe2cd1289..f6a70be8b6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -19,7 +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 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 b400cc6e46..dd8da6334f 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@5e5931c8c07cba504758b55ee8b6c4da6729f86c # templates#449 + - uses: munich-quantum-toolkit/templates@e9759ccc9a0efb6416ebe62ae4da7528d4a75d96 # templates#449 with: token: ${{ steps.create-token.outputs.token }} name: Core diff --git a/AGENTS.md b/AGENTS.md index 6df683eadf..9986fa1591 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). - Describe user-facing changes in PR descriptions. Prepare changelog entries - during release preparation; feature and fix PRs do not need them. Document - migrations from released APIs, not intermediate unreleased designs. + Describe user-facing changes and required migrations in PR descriptions. + Prepare the changelog and upgrade guide during release preparation; feature + and fix PRs do not need entries in either file. 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/UPGRADING.md b/UPGRADING.md index 2754c103d3..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 @@ -1250,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 d5756b842c..71b7bff798 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. Describe user-facing changes in the PR description; 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,9 +628,10 @@ releases may include breaking changes. To inform users about changes to the project, we maintain a {doc}`changelog ` and an {doc}`upgrade guide `. -Prepare the changelog in release-preparation PRs. Feature and fix PRs do not -need changelog entries. Describe their user-facing effects and limitations in -the PR description, and apply the relevant labels for Release Drafter. +Prepare the changelog and upgrade guide in release-preparation PRs. Feature and +fix PRs do not need entries in either file. Describe their user-facing effects, +limitations, and migration instructions in the PR description, and apply the +relevant labels for Release Drafter. The changelog format is based on a mixture of [Keep a Changelog] and [Common Changelog]. There are the following categories: @@ -652,28 +653,25 @@ During release preparation, follow these guidelines: - 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 entries 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. +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. -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. +During release preparation, 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. ## 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 changelog entries 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, +- 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, diff --git a/docs/development.md b/docs/development.md index 85d251536e..61c9e930a6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -229,9 +229,10 @@ requested. ## Release documentation -Prepare `CHANGELOG.md` in release-preparation PRs. Feature and fix PRs do not -need changelog entries. Their descriptions must explain user-facing changes and -limitations, with relevant labels for Release Drafter. +Prepare `CHANGELOG.md` and `UPGRADING.md` in release-preparation PRs. Feature +and fix PRs do not need entries in either file. Their 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 @@ -244,28 +245,29 @@ 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 `UPGRADING.md` with the PR -that introduces them. Give the replacement, changed semantics, or lack of a -replacement. Summarize these changes in `CHANGELOG.md` during release -preparation. Do not add migrations between intermediate unreleased APIs. -Preserve published release sections except when correcting a verified error. - -Before a release, prepare the changelog 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 +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` contains only published releases. Create the -next section during release preparation and finalize its 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. +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 From ae0182450e37af4146609e8834d8b4dd9d272455 Mon Sep 17 00:00:00 2001 From: Simon Hofmann Date: Mon, 14 Sep 2026 00:41:13 +0200 Subject: [PATCH 3/4] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20Pin=20merged=20release?= =?UTF-8?q?=20documentation=20templates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– *AI text below* πŸ€– Pin Templates #449 at merge commit 377a3dcd360ed3e4d879901dbda7d21e889f435b and regenerate the shared files. Align Core’s release policy with the merged guidance on changelog and upgrade-guide edits. Assisted-by: GPT-6 via Codex --- .github/workflows/templating.yml | 2 +- AGENTS.md | 8 ++-- docs/contributing.md | 66 +++++++++++++++++--------------- docs/development.md | 4 +- 4 files changed, 42 insertions(+), 38 deletions(-) diff --git a/.github/workflows/templating.yml b/.github/workflows/templating.yml index dd8da6334f..d27d1a9af6 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@e9759ccc9a0efb6416ebe62ae4da7528d4a75d96 # templates#449 + - uses: munich-quantum-toolkit/templates@377a3dcd360ed3e4d879901dbda7d21e889f435b # templates#449 with: token: ${{ steps.create-token.outputs.token }} name: Core diff --git a/AGENTS.md b/AGENTS.md index 9986fa1591..978329abbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,10 +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). - Describe user-facing changes and required migrations in PR descriptions. - Prepare the changelog and upgrade guide during release preparation; feature - and fix PRs do not need entries in either file. 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/docs/contributing.md b/docs/contributing.md index 71b7bff798..723438909e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -628,10 +628,36 @@ releases may include breaking changes. To inform users about changes to the project, we maintain a {doc}`changelog ` and an {doc}`upgrade guide `. -Prepare the changelog and upgrade guide in release-preparation PRs. Feature and -fix PRs do not need entries in either file. Describe their user-facing effects, -limitations, and migration instructions in the PR description, and apply the -relevant labels for Release Drafter. +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. + +(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, +- 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. The changelog format is based on a mixture of [Keep a Changelog] and [Common Changelog]. There are the following categories: @@ -657,33 +683,11 @@ 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. -During release preparation, 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. - -## 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, -- 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. +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 diff --git a/docs/development.md b/docs/development.md index 61c9e930a6..54ed6e2cc9 100644 --- a/docs/development.md +++ b/docs/development.md @@ -229,8 +229,8 @@ requested. ## Release documentation -Prepare `CHANGELOG.md` and `UPGRADING.md` in release-preparation PRs. Feature -and fix PRs do not need entries in either file. Their descriptions must explain +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. From aec0f1677971bd8d21849607dbd6a2f5466d9c58 Mon Sep 17 00:00:00 2001 From: Simon Hofmann Date: Mon, 14 Sep 2026 07:42:44 +0200 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=9D=20Correct=20the=20merged=20tem?= =?UTF-8?q?plate=20pin=20comment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– *AI text below* πŸ€– Label the pinned template commit as main now that Templates #449 has merged. Keep the exact commit pin unchanged. Assisted-by: GPT-6 via Codex --- .github/workflows/templating.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/templating.yml b/.github/workflows/templating.yml index d27d1a9af6..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@377a3dcd360ed3e4d879901dbda7d21e889f435b # templates#449 + - uses: munich-quantum-toolkit/templates@377a3dcd360ed3e4d879901dbda7d21e889f435b # main with: token: ${{ steps.create-token.outputs.token }} name: Core