Version of language bindings, api wrappers, etc #259

New Issue

GiteaMirror · 2026-02-17T11:42:03-06:00

GiteaMirror commented

2026-02-17 11:42:03 -06:00

Originally created by @Playermet on GitHub (Feb 13, 2017).

How should be versioned language bindings/wrappers?

Original api:

May use semver, or not.
May be updated in 3 ways (major, minor, patch).

Binding/wrapper:

Possess their own api and changes (even if original api still same).
Depended on original api, and follows for its updates.

Just merging both changes in single x.y.z causes disorientation, which grows with time.

Originally created by @Playermet on GitHub (Feb 13, 2017). How should be versioned language bindings/wrappers? Original api: 1) May use semver, or not. 2) May be updated in 3 ways (major, minor, patch). Binding/wrapper: 1) Possess their own api and changes (even if original api still same). 2) Depended on original api, and follows for its updates. Just merging both changes in single x.y.z causes disorientation, which grows with time.

GiteaMirror closed this issue

2026-02-17 11:42:04 -06:00

GiteaMirror commented

2026-02-17 11:42:05 -06:00

@jwdonahue commented on GitHub (Nov 30, 2017):

@Playermet, what is meant by "binding/wrapper". I am not following your scenario.

@jwdonahue commented on GitHub (Nov 30, 2017): @Playermet, what is meant by "binding/wrapper". I am not following your scenario.

GiteaMirror commented

2026-02-17 11:42:06 -06:00

@nrabinowitz commented on GitHub (Feb 20, 2018):

This is an old issue, but I have the same (or a similar) question.

Imagine I have a C library called Foo, and I make a JS binding called FooJS, both using semver
I would like the version of Foo.js to reflect the semver of Foo, so that FooJS v2.1.2 would be a binding to Foo v2.1.2 (this is option 2 for the binding as outlined above). This has lots of advantages - clarity for the end user, guarantee that the binding updates following the core lib's guarantees for semver, etc.
However, assuming the binding has a few non-trivial details, if I need to fix the binding while maintaining the core lib's version I'm not sure how to proceed. If I use FooJS v.2.1.2-1 this is considered an unstable pre-release version by most clients. If I bump the patch version on FooJS I am out of sync with the core Foo library, a state that gets even worse on the next Foo patch bump.

How does semver handle this situation?

@nrabinowitz commented on GitHub (Feb 20, 2018): This is an old issue, but I have the same (or a similar) question. * Imagine I have a C library called `Foo`, and I make a JS binding called `FooJS`, both using semver * I would like the version of `Foo.js` to reflect the semver of Foo, so that `FooJS v2.1.2` would be a binding to `Foo v2.1.2` (this is option 2 for the binding as outlined above). This has lots of advantages - clarity for the end user, guarantee that the binding updates following the core lib's guarantees for semver, etc. * However, assuming the binding has a few non-trivial details, if I need to fix the binding while maintaining the core lib's version I'm not sure how to proceed. If I use `FooJS v.2.1.2-1` this is considered an unstable pre-release version by most clients. If I bump the patch version on `FooJS` I am out of sync with the core `Foo` library, a state that gets even worse on the next `Foo` patch bump. How does semver handle this situation?

GiteaMirror commented

2026-02-17 11:42:06 -06:00

@jwdonahue commented on GitHub (Feb 22, 2018):

Ok this is a package A depends on package B scenario and SemVer is not intended to provide dependency data. That said, you can always put +Foo.1.0.0 on the FooJS "binding" (adapter) if the packaging tool you are using supports the SemVer meta-tag. Most packaging tools have much better support for defining dependencies between SemVer compliant products, than by abusing the SemVer string itself however.

@jwdonahue commented on GitHub (Feb 22, 2018): Ok this is a package A depends on package B scenario and SemVer is not intended to provide dependency data. That said, you can always put +Foo.1.0.0 on the FooJS "binding" (adapter) if the packaging tool you are using supports the SemVer meta-tag. Most packaging tools have much better support for defining dependencies between SemVer compliant products, than by abusing the SemVer string itself however.

GiteaMirror commented

2026-02-17 11:42:07 -06:00

@jwdonahue commented on GitHub (Feb 22, 2018):

So basically, SemVer was not intended nor is it designed to solve this problem. You should use the SemVer string to designate the version of your interface or package. SemVer does not define how dependency graphs are documented. SemVer defines one kind of version string that would be part of the data at the nodes in the dependency graph. This is where packaging tools like npm and nuget come into play. They provide the means to define one node and all of its immediate neighbors, along with the tools to resolve the entire graph below that one node. As an engineer with 28 years of experience shipping products at every scale, I would advice that you should never pin the FooJS version to the Foo version. Such a decision will eventually cause you much grief.

@jwdonahue commented on GitHub (Feb 22, 2018): So basically, SemVer was not intended nor is it designed to solve this problem. You should use the SemVer string to designate the version of your interface or package. SemVer does not define how dependency graphs are documented. SemVer defines one kind of version string that would be part of the data at the nodes in the dependency graph. This is where packaging tools like npm and nuget come into play. They provide the means to define one node and all of _its_ immediate neighbors, along with the tools to resolve the entire graph below that one node. As an engineer with 28 years of experience shipping products at every scale, I would advice that you should never pin the FooJS version to the Foo version. Such a decision will eventually cause you much grief.

GiteaMirror commented

2026-02-17 11:42:08 -06:00

@jwdonahue commented on GitHub (Feb 22, 2018):

@Playermet, unless you have further questions, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Feb 22, 2018): @Playermet, unless you have further questions, please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-02-17 11:42:09 -06:00

@jwdonahue commented on GitHub (Feb 27, 2018):

Related: #265

@jwdonahue commented on GitHub (Feb 27, 2018): Related: #265

GiteaMirror referenced this issue

2026-04-16 10:15:17 -05:00

[GH-ISSUE #259] Non-linear developement #1049

GiteaMirror referenced this issue

2026-04-20 09:43:35 -05:00

[GH-ISSUE #259] Non-linear developement #1916

GiteaMirror referenced this issue