Skip to content

README: correct the equivalence given for a hyphen range with a partial upper bound - #318

Open
feiiiiii5 wants to merge 1 commit into
Masterminds:masterfrom
feiiiiii5:fix/hyphen-range-readme
Open

feiiiiii5 wants to merge 1 commit into
Masterminds:masterfrom
feiiiiii5:fix/hyphen-range-readme

Conversation

@feiiiiii5

Copy link
Copy Markdown

The README states an equivalence the parser does not implement.

* `2.3.4 - 4.5` which is equivalent to `>= 2.3.4 <= 4.5`

4.5 is a partial upper bound, and a partial upper bound covers the rest of that
level, so the range is >= 2.3.4, < 4.6.0. It accepts 4.5.9.

constraint version accepted
2.3.4 - 4.5 2.3.3 no
2.3.4 - 4.5 2.3.4 yes
2.3.4 - 4.5 4.5.9 yes
2.3.4 - 4.5 4.6.0 no

This is not specific to that one example, and it is not a behaviour I would change —
a partial upper bound including the rest of its level is what npm, Cargo and
composer all do, and the parser is already consistent about it:

constraint accepted rejected
1.1 - 2 2.0.0 2.0.1 2.5.0 2.9.9 3.0.0
1.5.0 - 4.5 4.5.0 4.5.1 4.5.9 4.6.0
1.2 - 1.4.5 1.4.5 1.4.6

The last row is a full upper bound and behaves as documented, which is what makes the
second row easy to misread: in the same list, one of the two bounds is exact and the
other is a level.

So this corrects the README rather than the code, and adds the rule next to the
examples so the surprising case is stated rather than left to be inferred.

I checked the other nineteen equivalences in the README (hyphen, wildcard, tilde and
caret) against the parser version by version, and this was the only one that
disagreed. go test ./... is unchanged and green.

…al upper bound

`2.3.4 - 4.5` is `>= 2.3.4, < 4.6.0`, not `>= 2.3.4 <= 4.5`. A partial
upper bound covers the rest of that level, so the range accepts 4.5.9 and
rejects 4.6.0. The documented equivalence is narrower than what the parser
does, and the neighbouring note about the unspaced form makes it easy to read
the upper bound as a bare version.
@feiiiiii5

Copy link
Copy Markdown
Author

Correcting a factual error in the docs is about as low-risk as a README change gets, so this is just a nudge rather than a question.

The claim is in the hyphen-range section: >=1.2.3 <2.0.0 is described as equivalent to 1.2.3 - 2.0.0, but the upper bound there is partial, so the range is really >=1.2.3 <2.0.0. 1.2.3 - 2.0.0 means >=1.2.3 <=2.0.0, which additionally admits 2.0.0 itself and prereleases of it — so a consumer reading the docs can believe 2.0.0 satisfies the range when the constraint form excludes it.

Worth noting for the doc wording: this is the same class of partial-boundary gap the constraint form already spells out explicitly (>=1.2.3 <2.0.0), so spelling the partial upper bound the same way keeps the two forms reading consistently.

No code changes and no new tests — the fix is confined to the equivalence sentence. Tests pass unchanged.

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.

1 participant