Resolved: rust-bitcoinconsensus versioning scheme is broken

[tcharding]

rust-bitcoinconsensus uses a technically semver compliant kludge for its version number 0.20.2-0.5.0 to show the Core version and the crate version. The idea was that we could then move to 0.20.2-0.6.0 and be following all the semver rules. Turns out cargo seems to ignore the stuff after the - so the recent release was not semver compliant because it remove stuff in a point release.

We need a new versioning scheme for rust-bitcoinconsensus in order to be able to do the next release.

[tcharding]

For context see:

• Derive additional traits for error type rust-bitcoinconsensus#72
• Failure to build dependent crates due to missing trait derivations rust-bitcoinconsensus#73
• v0.20.2-0.6.1 Broke rust-bitcoin 0.30.2 rust-bitcoinconsensus#74

And the other discussion where I announced the breakage

• I just broke the `rust-bitcoin` build #2273

[apoelstra]

I continue to like x.y.z where x.y is the Bitcoin release and z is our own patch release counter.

@Kixunil argued elsewhere that this sucks because it makes every single Bitcoin Core release into a semver-breaking change for us. My view is that some releases will be a semver-breaking change anyway (e.g. when the verification function is updated to take more context, as in Taproot) so we need to handle this downstream anyway. Also, in cases where there are actually no breaking changes, then we can semver-trick it.

Another sensible option would be to take 0.21.0, the next available "major" version, and then bump from there in the normal Rust-ic way, independent of the underlying version of Bitcoin.

A hybrid of these would be to combine the two approaches, and swap the "Rust part" and the "Core part" of the version number. Then the Core part is what will get ignored by cargo, and the Rust part is in our control.

[Kixunil]

Yes, some will be and we will have to handle it downstream. That doesn't mean we should make more breaking changes and additional work with semver tricks just to get core-ours versioning. I see no value in having the numbers in that order. As @dpc said below, just changing it to ours+core is much clearer.

[TheBlueMatt]

Why did we not end up with our.version.stuff-bitcoin.core.version? That would basically mean cargo ignores the Bitcoin Core version, which I think is fine, as long as we bump our version when we actually have an API change.

[tcharding]

said like Cartman, for anyone that missed it :)

[Kixunil]

The biggest issue with this is our.version.stuff has to get some offset to always be bigger than the current 0.20.X

Why is that the biggest issue? If we stop bumping the minor number every Core release then it will never be higher than whatever we start with.

Also I suggest we start with 0.100.0 to make it absolutely obvious it's not a Core version and we just changed versioning.

[tcharding]

Oh didn't see this before I posted.

[tcharding]

Below I suggest 0.106.0+0.20.2 using 6 for some continuity?

[tcharding]

If we stop bumping the minor number every Core release

Wouldn't the next version with newer Core then be 0.107.0+0.21.2?

[tcharding]

our.version.stuff-bitcoin.core.version

While I believe that works its ugly for the reason you mention, we'd have to offset our version number.

Another sensible option would be to take 0.21.0, the next available "major" version, and then bump from there in the normal Rust-ic way, independent of the underlying version of Bitcoin.

I like this idea for releases of Core 0.20.2 and 0.21.2

I continue to like x.y.z where x.y is the Bitcoin release and z is our own patch release counter.

Once we get to Core 22 I think we should do this. (But like you say, @Kixunil has some disagreement that I'm not fully understanding).

[Kixunil]

we'd have to offset our version number

Why is that a problem? It's just a number. Or we could eventually release 1.0 and there's no offset. :)

@Kixunil has some disagreement that I'm not fully understanding

What do you not understand? Cargo compares the version numbers numerically, the leftmost being most significant and the usual meaning of bumping the leftmost non-zero number is "breaking change" so if we bump it for no reason other than Core upgrading it falsely signals "breaking change" and then we and all downstream dependencies get to do more work to fix it up. Why should we create more work for us every time Core releases just to get the numbers in some specific order?

[tcharding]

Perhaps we can work through the versioning for 4 LTS releases (the 4 active Core release branches)

• 1.?.?+23.2
• 1.?.?+24.2
• 1.?.?+25.1
• 1.?.?+26.0 (when it is released)

And that if/when Core releases 25.2 what do we do?

[tcharding]

FTR I think we have all agreed on 0.100.0+0.20.2 for the next release.

[Kixunil]

And that if/when Core releases 25.2 what do we do?

We bump our patch version. Which implies that there's no mapping between our versions and Core ones. Which I think is the right thing to do unless you have some very specific reason to interact with Core versions somehow.

[dpc]

Isn't what you want x.y.z+<core-version>, where you just update z every time you release new +<core-version> (or y or even x if you want it to be a incompatible version. +... is a "build number" and is completely ignored for all purposes other than informative. Example: https://crates.io/crates/librocksdb-sys/versions

[Kixunil]

Oh, yes, this is exactly what we should do.

[tcharding]

I'm good with this, wish I thought of it before doing it backwards like I did. Anyways, the remaining question is what version number to start with (because it has to be bigger than 0.20.2-0.6.1, at first blush I propose 0.106.0+0.20.2 - although that does look a bit silly.

[Kixunil]

Why 106? I agree with 100+ to make it obvious it's not a Core version I'm just curious about 6.

[tcharding]

Just because it follows on from the 0.5.0 in the current versioning scheme. I'm don't really care though because I'm mainly focused on getting us to the LTS releases.

[tcharding]

Next release version number 0.100.0+0.20.2

Can I get some thumb emojis on this post if this is agreed please.

[tcharding]

Props to @dpc, coming through with the knowledge.

[tcharding]

Thanks all, marking this as resolved. Please see rust-bitcoin/rust-bitcoinconsensus#76 if you are interested.