Skip to content

docs: clarify that partial comparator expansions are not substitution-safe - #353

Open
TrueFurina wants to merge 1 commit into
dtolnay:masterfrom
TrueFurina:docs/op-expansion-not-substitution-safe
Open

TrueFurina wants to merge 1 commit into
dtolnay:masterfrom
TrueFurina:docs/op-expansion-not-substitution-safe

Conversation

@TrueFurina

Copy link
Copy Markdown

Fixes #350 (option 2: keep the matcher behavior intentional, make the docs not
overclaim).

Problem

The Op docs describe partial comparators with "equivalent to", e.g. >I.J
equivalent to >=I.(J+1).0. At the public VersionReq::matches API these
expansions are not substitution-safe once prerelease admission is involved
across multiple comparators:

let v = Version::parse("1.3.0-alpha").unwrap();
// both true:
VersionReq::parse(">1.2, >=1.3.0-alpha").unwrap().matches(&v),
// replacing `>1.2` with its documented expansion flips it to false:
VersionReq::parse(">=1.3.0, >=1.3.0-alpha").unwrap().matches(&v),

Both reproducers from #350 were verified locally against semver 1.x
(assertions hold exactly as reported).

Fix (docs-only)

  • The expansion bullets now read "expands to" instead of "equivalent to",
    describing how each form is interpreted on its own rather than claiming a
    rewrite rule.
  • A short preamble on Op states explicitly that the expansions are not
    freely substitutable inside a multi-comparator VersionReq when prerelease
    admission is involved, and to prefer the form matching your intent.
  • No behavior change; matcher and tests untouched.

Verification

@TrueFurina

Copy link
Copy Markdown
Author

Friendly ping - this is still open on my side and mergeable as far as I can tell. Happy to address any remaining feedback if something is blocking it. Thanks!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Partial comparators and their fully specified forms are not interchangeable with prerelease

1 participant