📝 update upgrading guide for new stub generation flow

[burgholzer]

Description

Revised the UPGRADING.md to reflect changes in the stub generation process. Added new commands and steps for improved clarity and streamlined execution.

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.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Updated build and upgrade process guidance with refined tooling configuration and improved validation steps.

• Chores

  • Enhanced build system handling with improved dependency synchronization and additional code quality checks.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

The UPGRADING.md file is updated to refactor the nox-based stub generation workflow. Changes include adding flags to uv sync, converting nanobind.stubgen invocation from a direct function call to Python module execution, extending stub generation with output location and pattern specifications, and introducing pre-check tooling with flexible exit code handling.

Changes

Cohort / File(s)	Change Summary
Build Workflow Documentation UPGRADING.md	Updates nox uv sync with --no-dev and --group "build" flags; refactors nanobind.stubgen invocation to run as Python module with session.run(); adds output location, pattern file, and module specifications; introduces prek installation and flexible exit code handling (0 or 1) for tooling runs; appends final ruff-check step for cleanup verification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Review the correctness of nox command syntax changes and new flag combinations
• Verify stub generation arguments map correctly from old invocation style to new module-based style
• Confirm exit code handling logic aligns with tool expectations (especially prek and ruff behavior)

Possibly related PRs

• 👷 Add step for checking if Python stub files are up to date #286: Modifies how nanobind.stubgen is invoked and adds workflow step to check stub generation status.
• 🚸 change to nox -s stubs for driving stub generation #288: Updates stub-generation workflow and UPGRADING.md to use nox-driven "stubs" session with nanobind stub generation and prek-based checks.

Suggested labels

python, continuous integration

Poem

🐰 A nox-bound journey, stub by stub,
From main calls freed, now modules run,
With prek at the gate and ruff to clean,
The workflow gleams—fresh and lean!
Python marches forward, steady and true. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly references updating the upgrading guide for a new stub generation flow, which aligns with the main changes to UPGRADING.md.
Description check	✅ Passed	The description covers the main change and includes a completed checklist, though it lacks specific details about motivation, dependencies, and issue references.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-upgrade-guide

---

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2acb397 and 5774cc4.

📒 Files selected for processing (1)

• UPGRADING.md (2 hunks)

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1383
File: bindings/dd/register_matrix_dds.cpp:64-109
Timestamp: 2025-12-15T01:54:22.129Z
Learning: In the munich-quantum-toolkit/core repository, after migrating to nanobind, docstrings for Python bindings are now added directly in the C++ binding code (using R"pb(...)pb" syntax) and stub files (.pyi) are auto-generated using the `bindings/generate-stubs.sh` script. This replaces the previous pybind11 approach where docstrings were manually maintained in stub files.

Learnt from: burgholzer
Repo: munich-quantum-toolkit/yaqs PR: 212
File: CHANGELOG.md:12-15
Timestamp: 2025-10-14T14:37:38.047Z
Learning: In the munich-quantum-toolkit/yaqs project, changelog entries follow the template: "- $TITLE ([#$NUMBER]($URL)) ([**AUTHOR**](https://github.com/$AUTHOR))". Issue references should not be included in changelog entries; the PR number is sufficient for traceability.

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1360
File: .github/workflows/reusable-mlir-tests.yml:40-43
Timestamp: 2025-12-05T17:45:37.602Z
Learning: In the munich-quantum-toolkit/core repository, patch releases of LLVM dependencies don't require documentation updates, changelog entries, or additional tests beyond what's validated by passing CI checks.

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1383
File: python/mqt/core/ir/operations.pyi:9-16
Timestamp: 2025-12-15T01:59:17.023Z
Learning: In the munich-quantum-toolkit/core repository, stub files (.pyi) are auto-generated by nanobind's stubgen tool and should not be manually modified for style preferences, as changes would be overwritten during regeneration.

Learnt from: burgholzer
Repo: munich-quantum-toolkit/core PR: 1355
File: bindings/fomac/fomac.cpp:227-264
Timestamp: 2025-12-07T01:21:27.544Z
Learning: In the munich-quantum-toolkit/core repository, docstrings for Python bindings are added to the corresponding stub files (.pyi) rather than directly in the pybind11 C++ bindings code. This practice may change if the project adopts nanobind with automatic stub generation.

📚 Learning: 2025-12-15T01:54:22.129Z

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1383
File: bindings/dd/register_matrix_dds.cpp:64-109
Timestamp: 2025-12-15T01:54:22.129Z
Learning: In the munich-quantum-toolkit/core repository, after migrating to nanobind, docstrings for Python bindings are now added directly in the C++ binding code (using R"pb(...)pb" syntax) and stub files (.pyi) are auto-generated using the `bindings/generate-stubs.sh` script. This replaces the previous pybind11 approach where docstrings were manually maintained in stub files.

Applied to files:

• UPGRADING.md

📚 Learning: 2025-12-15T01:59:17.023Z

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1383
File: python/mqt/core/ir/operations.pyi:9-16
Timestamp: 2025-12-15T01:59:17.023Z
Learning: In the munich-quantum-toolkit/core repository, stub files (.pyi) are auto-generated by nanobind's stubgen tool and should not be manually modified for style preferences, as changes would be overwritten during regeneration.

Applied to files:

• UPGRADING.md

🔇 Additional comments (3)

UPGRADING.md (3)

26-28: Verify that uv sync flags align with project standards.

The added --no-dev and --group build flags are appropriate for a build-only environment, but please ensure these flags are consistent with how the project configures dependency groups elsewhere (e.g., in pyproject.toml or other nox sessions).

---

35-53: Stub generation invocation uses correct CLI flags.

The conversion to python -m nanobind.stubgen with flags --recursive, --include-private, --output-dir, --pattern-file, and --module aligns with the official nanobind CLI documentation. The example is clear and correctly uses the documented options.

---

57-67: Verify the intent of flexible success codes for prek tools.

The pattern of using success_codes=[0, 1] for intermediate prek runs followed by a final ruff-check without this parameter is defensive and ensures a clean final state. However, you should verify that prek-wrapped tools (license-tools, ruff-check, ruff-format) actually return exit code 1 when they make modifications rather than when errors occur, to ensure the success codes semantics are correct for this use case. The pattern also aligns with nanobind's overall approach of automating linting and formatting in stub generation workflows.

---

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

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