Easy check for version compatibility?

[garretwilson]

On first glance the library looks nice. But then I try to do something simple, one of the basic things of semantic versioning: check for minor-version compatibility. How do I do that?

For example:

if(ver1.isMinorVersionCompatible(ver2)) {
  //the APIs are compatible
}

Isn't that the whole point of semantic versioning? Maybe I missed such a comparison method in your documentation.

[zafarkhaja]

Hey @garretwilson, thanks for the feedback.

What you need is SemVer Expressions API (Ranges). Particularly take a look at Tilde ranges

Version v = Version.valueOf("1.2.3");
boolean result = v.satisfies("~1.2");

Hope this helps.

[garretwilson]

But what if I don't know what the major number is? I just want to make sure two things are compatible. Am I expected to convert the first version to a string, prepend a tilde, and then pass the resulting string to satisfies()? That seems convoluted and error-prone. Why should I do all this string manipulation?

Besides, checking minor version compatibility is one of the central if not the central usage of semantic versions (along with minor version compatibility). There should be a dedicated method for this.

[garretwilson]

In fact I gave you an example of what I want to do. Can you show me how to do that with jsemver, using the variables ver1 and ver2? I note that you did not give me code equivalent to what I asked --- probably because it is very difficult with jsemver.

[garretwilson]

To be fair, now that I think about it, I can just compare the major versions manually. Still, it would be nice to have a dedicated semantic method.

And what about checking patch-version compatibility (i.e. the major and minor versions are the same)?

[zafarkhaja]

Ok, I get it now. The reason why there is no such method is that I strived to keep the API small and simple and add methods only when there are obvious use cases and new methods really add some value to the library. So, I believe there should be a use case for every API method. Honestly, I've never come across a use case where you'd not care about major versions. I'm not saying there isn't such use case, it's just I haven't seen one. The typical use case for versions compatibility is package/dependency managers but they really do care about major versions.

Nevertheless, it's not difficult to implement it. If I correctly understand the logic behind your isMinorVersionCompatible method you could do something along these lines

if (ver1.getMajorVerison() == ver2.getMajorVerison() && 
    ver1.getMinorVerison() == ver2.getMinorVerison()
) {
    // minor version compatibility
}

I agree that manually comparing major and minor versions is not nearly convenient as having a dedicated method, so if you provide a valid use case for methods like isMajorCompatible and isMinorCompatible I don't see any reason why we couldn't add these methods to the API.

[garretwilson]

... if you provide a valid use case ...

Um, I thought that was self evident, and actually the use case comes by definition of semantic versioning, but since you asked: here's a quote from http://semver.org/ :

A simple example will demonstrate how Semantic Versioning can make dependency hell a thing of the past. Consider a library called "Firetruck." It requires a Semantically Versioned package named "Ladder." At the time that Firetruck is created, Ladder is at version 3.1.0. Since Firetruck uses some functionality that was first introduced in 3.1.0, you can safely specify the Ladder dependency as greater than or equal to 3.1.0 but less than 4.0.0. Now, when Ladder version 3.1.1 and 3.2.0 become available, you can release them to your package management system and know that they will be compatible with existing dependent software.

[garretwilson]

Also see the summary at http://semver.org/ . And the specification. Heck, read the whole thing. The whole point of semantic versioning is to know what you can depend on (or not) if certain components of the version number change. Therefore it seems obvious to me that any API working with semantic versions would want a simple, semantic method for determining if those components have changed.

[zafarkhaja]

No need to be so dramatic, I know what SemVer is all about. It's just the value of such methods wasn't clear to me at first, that's why I asked you for a use case. But having given it some thought yesterday I think I came up with a valid use case on my own. So let's do it! Care to submit a pull request to the release-0.10.0 branch? Or, I'll do it myself tonight.

[garretwilson]

Care to submit a pull request...

Unfortunately we have a tight deadline for feature completion this week, so I already wrote our own custom solution with an existing class we had.

I'll keep JSemVer in mind for our next release, though. Maybe it will support everything we need by then. Good luck.

[zafarkhaja]

Ok, thank you anyway for the feedback. Feel free to contact me through the issues here if you ever have any questions/suggestions regarding JSemVer in the future. Cheers.

[RobertFischer]

@zafarkhaja — If this is still outstanding, I'll work on it and submit a pull request for it.

[zafarkhaja]

Hey @RobertFischer it's already done in the release-0.10.0 branch. I'll be releasing it soon. Thanks.

[RobertFischer]

Looking forward to it!

[zafarkhaja]

Hello guys! Sorry for the delay and thank you for your contributions!