composer
[Documentation] It's not clear that this package does not follow the semver.org specification
I'm not asking you to reverse the decision in #15 not to follow the actual semantic versioning specification. I'm asking you to please make it clear in the package description and documentation that this package implements a version_compare()-compatible versioning system rather than following semver.org's rules.
For example,
// This outputs "true". Per semver.org, these are not equal.
var_dump( \Composer\Semver\Comparator::equalTo( "1.2.3-alpha", "1.2.3-a" ) );
// This outputs "true". Per semver.org, prerelease string "c" > "a".
var_dump( \Composer\Semver\Comparator::lessThan( "1.2.3-c", "1.2.3-a" ) );
// This outputs "true". Per semver.org, 1.2.3-prerelease is less than 1.2.3, not greater than.
// (version_compare considers "p" as meaning "patchlevel", along the lines of what might otherwise be "1.2.3.1").
var_dump( \Composer\Semver\Comparator::greaterThan( "1.2.3-prelease", "1.2.3" ) );
Again, I'm not asking you to change any of those results. But please make it clear in the documentation that if someone is looking for a package to follow semver.org rather than version_compare(), they should keep looking.
I suggest the following changes:
- Change the description to call it a "Version comparison library" rather than a "Semver library". https://github.com/composer/semver/blob/a40ea7eb72c7963be479663b9dd3e73a7d42a391/composer.json#L3
- Change the first line of the readme to call it a "Version comparison library" rather than a "Semver (Sementic Versioning) library". https://github.com/composer/semver/blob/a40ea7eb72c7963be479663b9dd3e73a7d42a391/README.md?plain=1#L4
- In the Version Comparison section, add a paragraph something like "This package compares versions in the same way PHP's
version_compare()does. It does not follow the specification at semver.org." before the existing paragraph linking to the details. https://github.com/composer/semver/blob/a40ea7eb72c7963be479663b9dd3e73a7d42a391/README.md?plain=1#L29-L33 - Remove the "semver" and "semantic" keywords. https://github.com/composer/semver/blob/a40ea7eb72c7963be479663b9dd3e73a7d42a391/composer.json#L6-L11
- Adjust the description of this repository to describe it as something like "Versioning utilities" rather than "Semantic versioning utilities".
(I'm not going to suggest renaming the package, namespaces, or classes. That would break too much stuff to be worth me advocating for.)
Thanks!
Yeah, we do follow the key parts of the semver spec, but cannot reasonably follow these minor details due to language support. So I disagree we should drop semver entirely because for most intents and purposes, this is quite semver compatible. But I agree that a warning in the readme at least is in order :)
And btw if you do want to send a PR for that, it'll for sure help resolve it sooner.