reflex-release: lift unshippable dependency pins when materializing a release

[masenf]

All Submissions:

• Have you followed the guidelines stated in CONTRIBUTING.md file?
• Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

The problem

A package that depends on a sibling it is waiting for pins the unreleased version — widget-core >= 0.2.0.dev1 — so the workspace resolves while the sibling is still unpublished. That pin cannot be published: *.dev versions never reach PyPI, so the metadata would be uninstallable. check-dev-pins rejects it at build time, which means someone has to remember to lift it once the sibling is out — and finds out at the publish gate, with the changelog already bumped, when they forget.

What this does

Materialization lifts the pin. Every dependency floor the release cannot ship is rewritten to the earliest published version that satisfies the whole requirement, uv.lock is re-resolved, and both land in the release commit alongside the changelog bump — through the same review.

Floor	Materializing a prerelease	Materializing a final version
>= 0.2.0.dev1	earliest published 0.2.0a1, 0.2.0, …	earliest published final 0.2.0, …
>= 0.2.0a1	left alone — an alpha may ship it	lifted to the earliest published final
>= 0.2.0	left alone	left alone

A floor no published version satisfies has nowhere to go, so the package is held back at plan time rather than materialized into a version that could never be published: auto-selected packages are dropped from the batch (a lockstep group whole, since its members only release together) and listed in the run summary, while an explicit selection fails the dispatch. Release the depended-on package first and the next release lifts the pin by itself.

Design notes worth reviewing

1. "Published" means tagged. Resolution reads the repository's own git tags, not PyPI — tags are created only after a successful upload, which is already this pipeline's record of what shipped. Offline, deterministic, no new network dependency in the plan step; the cost is that it only works for siblings, and that the release workflows must check out full history and tags (they do).
2. Dependencies outside the repository. A *.dev floor on one holds the release back (it is unpublishable regardless, and check-dev-pins would fail the build anyway); a prerelease floor on one is left alone, since its releases are not recorded here and pinning a beta is somebody's deliberate choice.
3. Lifting prerelease floors on a final release is beyond the literal problem, and closes it. Without it the feature leaks: an alpha release rewrites >= 0.2.0.dev1 to >= 0.2.0a1, check-dev-pins is satisfied, and the subsequent final release ships a floor that resolves users onto an alpha. Happy to scope this back to dev floors only if you would rather.
4. uv lock is the lock refresh, auto-detected from a root uv.lock and skipped when there is none. Not configurable — the tool already assumes uv everywhere (cli-command, setup-uv in every generated job).
5. Lockstep siblings under pin-exact are skipped, since pin-lockstep rewrites those to == <version> at build time and nothing declared here is shipped.
6. The upgrade is atomic and narrowly staged. Pin rewrites and the lock refresh succeed together or are rolled back, so a re-run never finds the pins already lifted and skips re-locking. materialize reports the paths it rewrote as a repinned output — it runs as a separate process from the delivery step — and _commit_changelogs (now _commit_materialized) stages exactly those beside the changelogs, so unrelated worktree edits stay out of the release commit.

dispatch_release.yml changes (the materialize step gains an id, the two delivery steps a REPINNED_JSON env), so adopting repos need a reflex-release sync; the PR drift check enforces it.

Changes To Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

uv run pytest tests/units/reflex_release — 299 passed (34 new here): bound resolution across both prerelease modes, the whole-specifier-set constraint, requirement rewriting that preserves extras/markers/other specifiers and relaxes a strict floor, TOML basic- and literal-string rewriting, the lockstep and outside-dependency exemptions, rollback on a failed lock and on a mid-batch failure, and the plan-time hold-back in explicit, auto and lockstep-group forms. ruff check, ruff format --check and pyright clean.

Rebased onto main now that #6888 has merged; the two features compose cleanly (verified the rendered workflows carry both the post-release dispatch step and the repinned threading).

[greptile-apps]

Greptile Summary

Materialization now replaces unshippable sibling dependency floors with the earliest suitable tagged release and refreshes the lock file atomically.

• Holds back packages when no published version can satisfy a dependency requirement.
• Threads rewritten paths into release delivery so only intended materialized files are committed.
• Updates generated workflow wiring, documentation, and unit coverage for pin resolution and rollback behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/reflex-release/src/reflex_release/devpins.py	Adds dependency-bound discovery, tag-based replacement selection, requirement-preserving TOML rewrites, lock refresh, and rollback handling.
packages/reflex-release/src/reflex_release/commands.py	Integrates blocked-pin filtering into planning and stages repinned files during materialized release delivery.
packages/reflex-release/src/reflex_release/cli.py	Accepts and forwards materialization’s repinned-path output to release delivery commands.
packages/reflex-release/src/reflex_release/templates/workflows/dispatch_release.yml	Threads the materialize step’s repinned output into both release delivery paths.
tests/units/reflex_release/test_devpins.py	Covers dependency resolution, requirement rewriting, lock handling, exemptions, and transactional rollback.
tests/units/reflex_release/test_commands.py	Covers plan-time holdbacks and committing materialized dependency changes.

_{Reviews (5): Last reviewed commit: "Scope the pin rewrite to published requi..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 27 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/reflex-release-dev-pin-upgrades-hluw0c (15e2f8d) with main (d3a17c7)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[masenf]

All four outstanding points addressed in 75e98b5. (The two shallow-clone threads @masenf already closed as by-design — agreed, and the README now says so where it explains that "published" means tagged.)

Strict floor rewritten wrong (P1) — a real bug, good catch. widget-core > 0.2.0.dev1 admits 0.2.0, so 0.2.0 is what it resolves to, and rewriting the operator verbatim produced > 0.2.0 — excluding the very release the requirement had just been lifted onto. Under an upper bound (> 0.2.0.dev1, < 0.3 with only 0.2.0 in range) it becomes unsatisfiable outright. A strict floor over an unreleased version now becomes an inclusive floor over the release above it.

I also added the invariant behind it: rewritten() now checks the result against the version it resolved to and fails rather than returning it. Reverting just the operator mapping, that check fires on its own — lifting 'widget-core > 0.2.0.dev1' produced 'widget-core > 0.2.0', which 0.2.0 does not satisfy — so a future gap in the operator handling can't publish metadata that resolves to nothing.

TOML escaping (P2) — real, and fail-safe rather than corrupting, but it aborts a release for a legal input. Confirmed the mechanism: for "widget-core >= 0.2.0.dev1; python_version > \"3.10\"", tomllib hands back the unescaped value, so the quoted search found 0 occurrences. Both spellings a value can have are now tried — an escaped basic string, and a literal string, which cannot escape anything. Not worth a round-tripping TOML dependency on the release path for this.

Non-atomic upgrade (P2) — real, though it needs a hand-run to bite. In CI a failed materialize fails the job on a throwaway checkout, so nothing is committed; locally the tree keeps lifted pins beside the old lock, and a re-run finds nothing left to lift, skips the refresh, and could commit exactly that pairing. The pyproject rewrites are now rolled back when uv lock cannot follow them, so a re-run has the same work to do.

Over-broad staging (P2) — you're right that the comment overclaimed. The obstacle was that materialize and the delivery step are separate processes, so the committing side could not know what had been rewritten. Fixed by making it known: materialize now emits a repinned output listing the paths, threaded to open-release-pr/push-prerelease the way releases already flows from plan. Only those paths are staged, so an unrelated uncommitted edit to a released package's pyproject.toml stays out of the release commit — there's a test for exactly that.

279 passing (6 new); ruff check, ruff format --check and pyright clean. Note dispatch_release.yml changed (the materialize step gained an id and the two delivery steps a REPINNED_JSON env), so this needs a reflex-release sync in any adopting repo — the PR drift check enforces it.

---

Generated by Claude Code

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[FarhanAliRaza]

Ran this for real rather than reading it: built a sandbox repo with a root package, a sibling, and tags at 0.1.0 / 0.2.0a1 / 0.2.0 / 0.3.0, then drove plan -> materialize -> push-prerelease through a dozen shapes.

The behaviour matches the README table. >= 0.2.0.dev1 lifts to >= 0.2.0 for a final and >= 0.2.0a1 for a prerelease; > 0.2.0.dev1 becomes >= 0.2.0; extras and a python_version > "3.10" marker survive untouched; a prerelease floor on an outside dep is left alone while a dev floor on one is held back; an unsatisfiable floor drops an auto-selected package (with a ### Held back summary) and fails an explicit one; the two-package rollback from the last commit really does restore both pyprojects and leave the fragments on disk; and the commit carries exactly the changelog, the fragment deletion and pyproject.toml, with an unrelated dirty file left out.

Two things I'd fix before merging, plus a few caveats — inline.

Two more that didn't have a good line to hang on:

• The pin's target version and the release action can disagree. >= 0.4.0.dev1 on a sibling at 0.3.0 plus release-patch produces 0.3.1, which still doesn't satisfy the floor, so the dependent stays held back until someone picks a minor. Worth a line in the README next to "the next release lifts the pin by itself".
• The rollback guard covers apply + lock but not the towncrier step after it. I made towncrier fail and pyproject.toml was left lifted. CI throws the worktree away so this only bites local runs — noting it rather than asking for a change.

Tests, ruff and pyright are clean (299 passed).