[simon1hofmann]

🤖 AI text below 🤖

Description

Feature and fix PRs currently edit shared Unreleased sections, causing merge conflicts. Prepare the changelog and upgrade guide in release-preparation PRs. Contributors describe user-facing changes, limitations, and required migrations in their PR descriptions so release maintainers can collect them.

Update the shared contributor guide, agent guidance, and PR checklist. Remove the per-PR changelog and upgrade-guide checkboxes. Agents must leave both files unchanged except in release-preparation PRs or when explicitly asked. Keep drafting, formatting, attribution, and migration guidance together in the release-preparation section. Release preparation uses Git history, merged PR descriptions, Release Drafter, and existing notes, accounting for backports and previously published changes. AI tools may draft release documentation; maintainers verify claims, links, attribution, and migration examples.

Implements the review discussion in Core #2550. Core adoption is tracked in Core #2556. Repositories adopt the change through a templates update. Generated files in this repository are left to its templating workflow.

Local validation: all 13 existing rendering tests passed, covering project types with and without changelog and upgrade-guide support; uv run prek run --all-files passed. This is a documentation change; no new tests are needed. CI for the updated head remains pending.

AI assistance: Codex drafted the guidance and ran validation.

Checklist

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

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[burgholzer]

Let's also drop the upgrade guide and generate that on the fly in release prep PRs.

[burgholzer]

This looks pretty good to me, thanks!
One last round of feedback. Please incorporate that and then feel free to merge once you are happy 😌

[denialhaag]

@simon1hofmann and @burgholzer, I'm not sure if I really want to roll this out in all repositories. Repositories that we don't maintain as actively as MQT Core might really benefit from a changelog and upgrade guide that gets updated continuously. 🤔

(Plus, when doing certain maintenance tasks, I would like to continue to write semi-consistent changelog and upgrade-guide entries in all repositories.)

[denialhaag]

In addition, this interferes with the current workflow in repositories that we don't maintain at all (e.g., MQT YAQS). There, I really don't want to roll this out.

[burgholzer]

@denialhaag i hear you.
I'd be fine with keeping this to MQT Core.
We can already specialize the AGeNTS file. And we could simply disable the changelog for MQT Core and do our own guide there.
Would that work?

[denialhaag]

@burgholzer, yeah, I was just about to write that we could decouple MQT Core 4 from the templates altogether at this point. MQT Core 4 sees so much more action than the other repositories, and at this point, the templates have become more of a headache than anything else. For all other repositories, I still feel it's genuinely useful to have up-to-date guidance that covers the generic parts so we don't have to create PRs manually.

There may still be a few exceptions. For example, we might still want to use the templated Renovate and Release Drafter configurations in MQT Core, but manually maintaining them also wouldn't be the end of the world.

[burgholzer]

@burgholzer, yeah, I was just about to write that we could decouple MQT Core 4 from the templates altogether at this point. MQT Core 4 sees so much more action than the other repositories, and at this point, the templates have become more of a headache than anything else. For all other repositories, I still feel it's genuinely useful to have up-to-date guidance that covers the generic parts so we don't have to create PRs manually.

There may still be a few exceptions. For example, we might still want to use the templated Renovate and Release Drafter configurations in MQT Core, but manually maintaining them also wouldn't be the end of the world.

I like that thought. 💭
Let's go with that. I think it is not too bad that we have to manually update MQT Core. All the time and complexity saved by not having to special case MQT Core in the templates should easily compensate for that.