✨ Add optional major-version cap for MQT Core updates

[denialhaag]

Description

🤖 AI text below 🤖

Add an optional max-major-version input so downstream projects can continue receiving MQT Core 3.x updates after v4 is released. Omitting the input keeps unrestricted updates; specifying a cap together with update-to-head: true is rejected.

Resolve the selected release tag to its commit so the updated version and revision refer to the same release.

AI notice

This PR and its contents were created with the assistance of GPT-6 Astra via Codex.

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

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.

[denialhaag]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e3698daa-d89a-495e-947e-d068d0384832

📥 Commits

Reviewing files that changed from the base of the PR and between 9d0a300 and 737d433.

📒 Files selected for processing (3)

• .github/workflows/reusable-mqt-core-update.yml
• CHANGELOG.md
• UPGRADING.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• New Features

  • Added an optional maximum major-version limit for MQT Core updates.
  • Updates now consider only eligible stable releases within the configured limit and skip updates when no suitable release is available.
  • Leaving the limit unset preserves unrestricted latest-release behavior.

• Bug Fixes

  • Added validation for invalid version limits and incompatible update settings.

• Documentation

  • Documented the new version-limiting option, supported values, and update behavior.

Walkthrough

The reusable workflow adds an optional max-major-version input, validates incompatible values, selects the highest eligible stable release, and uses validated GitHub API responses for downstream commit and version checks. Documentation describes the new input and update behavior.

Changes

MQT Core release bounds

Layer / File(s)	Summary
Input contract and documentation .github/workflows/reusable-mqt-core-update.yml, CHANGELOG.md, UPGRADING.md	The workflow accepts and validates max-major-version. The changelog and upgrade guide document its limits, exclusions, examples, and incompatibility with update-to-head.
Eligible release selection .github/workflows/reusable-mqt-core-update.yml	The workflow uses gh api to inspect releases, excludes drafts, prereleases, and invalid tags, and selects the highest release within the configured major-version limit.
Guarded commit and version checks .github/workflows/reusable-mqt-core-update.yml	The workflow validates tag and branch commit SHAs with jq. It runs downstream SHA, semver, and comparison steps only when an eligible release exists.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 737d4

The reusable update workflow now supports an optional major-version cap while preserving unrestricted updates when omitted and safely skipping updates when no eligible release exists. No merge-blocking risk is identified.

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ReusableWorkflow
  participant GitHubReleasesAPI
  participant GitHubRefsAPI
  Caller->>ReusableWorkflow: Set max-major-version and update options
  ReusableWorkflow->>ReusableWorkflow: Validate inputs
  ReusableWorkflow->>GitHubReleasesAPI: Query eligible releases
  GitHubReleasesAPI-->>ReusableWorkflow: Return selected release tag
  ReusableWorkflow->>GitHubRefsAPI: Fetch tag or main-branch commit SHA
  GitHubRefsAPI-->>ReusableWorkflow: Return validated SHA
  ReusableWorkflow->>ReusableWorkflow: Compare versions

Loading

Suggested reviewers: burgholzer

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: adding an optional major-version cap for MQT Core updates.
Description check	✅ Passed	The description includes the change summary, motivation, AI disclosure, checklist, changelog update, and upgrade-guide update. The self-review and personal-responsibility items remain unchecked, and d…

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}

[burgholzer]

Looks very reasonable 👍🏻