Clarify caret operator range for pre-1.0.0 dependencies

[greysteil]

I couldn't find any documentation on the behaviour of the caret operator for pre-1.0.0 dependencies, and it wasn't immediately obvious that it would behave in the same way as for post-1.0.0 dependencies (mainly because in JS it doesn't).

This PR adds a pre-1.0.0 example to the readme and adds a test for the current behaviour.

This may have been discussed elsewhere, but in combination withdep using the caret operator by default, the current behaviour here is a little surprising. I can imaging users setting version = "0.0.1" in their Gopkg.toml and being surprised/unhappy to get 0.0.3, which might include a host of breaking changes. Maybe that's better fixed in dep than here, though.

[cmaglie]

0.x.y is in the range of unstable releases, and they may break at any time, even for PATCH release: https://semver.org/#spec-item-4

In this particulare case you should consider 0.x.y to be compatible ONLY with itself. In other words ^0.x.y is equivalent to =0.x.y or >=0.x.y <0.x.y+1

[cmaglie]

Oh well, I've searched around a bit more and it seems that the correct interpretation is:

• ^0.0.y is equivalent to =0.0.y (for example ^0.0.3 is >=0.0.3 <0.0.4)
• ^0.x.y is equivalent to >=0.x.y <=0.x+1.0 (for exampe ^0.3.5 is >=0.3.5 <0.4.0.)

source: http://jubianchi.github.io/semver-check/

[mattfarina]

@greysteil Thanks for adding the documentation and test. It's worth noting the dep isn't using the version on the master branch but rather the version on the 2.x branch. I'm not entirely sure what we're going to do with that once vgo/modules is in and dep becomes overcome by that.

@cmaglie There is no spec on semver ranges. There are minor differences between JS, PHP, and others.

That being said, because we are talking about compatibility I did a little digging on behavior of the ^.

• npm does it as Clarify caret operator range for pre-1.0.0 dependencies #83 (comment) notes
• Composer/PHP uses the ^ for compatibility. See https://getcomposer.org/doc/articles/versions.md#caret-version-range-. That means below a 1.0.0 release it handles it based on Y in x.y.z.
• Cargo/Rust does it similar to npm. See https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#caret-requirements
• Gemfiles have the ~> which is sorta different but similar https://robots.thoughtbot.com/rubys-pessimistic-operator
• I think swift is similar to Ruby... https://github.com/apple/swift-package-manager/tree/master/Documentation

We should figure out what to do about the ^ operator.

I'm hesitant to change or document this at the moment. Documenting it clearly means it's expected behavior and not a bug for pre-1.0.0.

/cc @technosophos

[greysteil]

I've spent a lot of time looking a how different languages specify requirements (I have to convert them to Ruby requirements for Dependabot - code is here), so I'll add my 2 cents:

• Ignore what Ruby does with ~>. You already have ~, which is basically identical to that functionality. The ~> requirement is well loved in the Ruby community, but you already have an equivalent (and `~> doesn't have anything to do with SemVer)
• Composer actually behaves the same as npm and cargo, they just don't document it. See https://semver.mwl.be/#?package=rikudou%2Fcron-bundle&version=%5E0.0.1&minimum-stability=stable

Given the above, there are three options:

1. Fall in line with the de-facto definition of SemVer, which is what everyone else does. This is probably the most expected behaviour
2. Follow the spec strictly and insist on equality for pre-1.0.0 deps. This is makes the operator kinda redundant, though
3. Treat pre-1.0.0 deps the same at post 1.0.0 deps when using ^. This makes the definition of ^ simpler, but means it's not very useful for pre-1.0.0 deps

My hunch is that (1) is the right choice - it's basically what everyone now expects. At the end of the day you just have to make a choice on it, though 🤷‍♂️

[mattfarina]

Here is the plan.

1. I'm going to merge this and cherry pick it to the release-1 branch for semver 1.x. This will go out in the next release.
2. Rust and npm follow the same pattern for ~ and ^. PHP is different on ~ and I'm unsure of some pre 0.1.0 cases. I'll update semver 3.x to follow the rust and js pattern.

Sorry for the delay in getting around to this and thanks for all the input.