Proposal: npm package version should match native binary version (or clearly indicate it)

[ramvi]

When I install @openwallet-foundation/askar-react-native@0.3.2, I expect to get native binary v0.3.2. Instead, I silently get v0.4.1.

This caused hours of debugging when I encountered Xcode 16 LLVM incompatibility errors. I tried downgrading the npm package, assuming older versions would have older (compatible) native binaries. They don't.

What I found:

npm version	Expected native	Actual native
0.4.3	v0.4.3	v0.4.6
0.3.2	v0.3.2	v0.4.1
0.3.1	v0.3.1	v0.4.1
0.3.0	v0.3.0	v0.4.1

The only compatible native binary (v0.3.2, built with older LLVM) is not referenced by any npm package version.

Suggestion

Either:

1. Lock native version to npm version (1:1 mapping)
2. Use composite versioning like 0.4.3-native0.3.2 or 0.4.3+native.0.3.2 (similar to Debian/Ubuntu packaging)
3. At minimum: Don't retroactively update binary.version in already-published npm packages

Current workaround

I had to create a pnpm patch to force native v0.3.2:

-    "version": "v0.4.6",
+    "version": "v0.3.2",

[genaris]

I transfered the issue to the wrapper because I think it is something that might be discussed here.

There was a time where we used to have all wrappers in the main repo (alongside the native library), and we tried to match versions. But that would imply that any error or new feature in any of the wrappers (namely Python or JS) would trigger a new version update to the others and the native library as well, which wasn't ideal neither. So first it was decided to decouple versioning of the wrappers and maintain a compatibility table in the README, which is referenced in the npm package README as well.

I don't know if this answer the questions of this issue, but at least I tried to give the historical reasons and also to point out that the compatibility list is indicated (probably not as clearly as it should).

That being said, the README covers only until 0.3.x releases of this wrapper, so I think we must update it soon. It also doesn't mention anything that this wrapper replaces previous @hyperledger/aries-askar-* packages. I think it would be good to list the available versions under Hyperledger umbrella in the table as well, but clearly distinguish them from the OWF ones.

[TimoGlastra]

This caused hours of debugging when I encountered Xcode 16 LLVM incompatibility errors. I tried downgrading the npm package, assuming older versions would have older (compatible) native binaries. They don't.

Can you explain a bit more about the incompatibility? It's not the thing you opened this issue for, but I'm curious what build issues you're experiencing with newer versions.

We use the latest version of Askar in our wallet and haven't encountered any issues AFAIK ( @berendsliedrecht right?)

[TimoGlastra]

I created #75 to update the version compatibility table.

Regarding:

At minimum: Don't retroactively update binary.version in already-published npm packages

What do you mean with this? We never retroactively update the binary.version for an already published package. We do publish new package versions, but if you want you can lock it in your package.json (since the askar dependency is a peer dependency in Credo, so you decide in the end which version is installed)

Regarding the other appraoches, @genaris already explained why 1 doesn't work (we tried). For approach 2, it will mean there's no automatic semver updates anymore.

We weren't really aware of these build issues, and in this case it should have been a minor release (so bump 0.4 of the binary to 0.5 and this would have also triggered a bump in the wrapper version. So that's more an oversight on our side.

Which React Native version are you using? Should we also take Xcode version into consideration in the version compatibility table?