Rethinking version numbers

[cgwalters]

This came up in team chat but basically the proposal is to try to be "more semver" and bump the minor and not the patch version each time.

This would make our version numbers strongly resemble e.g. Rust's.

[cgwalters]

I guess though from my PoV it's kind of weird to have a permanent 1. in front of the version, and a near-permanent .0 a the end.

It's hard to say "never" but to me a giant part of the goal of this project is that we don't pull a "2.0" version or higher, i.e. we don't ever break compat.

And the chance that we release upstream patch fixes (given the release cadence) is pretty low.

So I dunno, a different alternative here is: Don't be semver. Instead we use the "minor" version bumps to denote larger features (perhaps once every 3 months?), and the patch version to denote smaller releases?

But, dunno...maybe that's really not significantly better enough than just saying we use semver.

[jeckersb]

I'm all for being "more semver", mostly because that's the most boring and expected thing that we can do. If I see a project with an X.Y.Z version scheme, I'm going to assume semver is implied. Better to not confuse people unnecessarily.

[cgwalters]

Contract...like "verbally"? I am not aware of anything actually parsing these numbers today; are you? One clearly could parse the output of bootc --version I guess...and maybe out of conservatism we should assume someone is doing so.

But can you flesh out a bit more how you see that contract, is it just a perceptual one or do you see anything code related there?

[vrothberg]

By "contract" I mean following the specification of semver. So it's more a verbal contract and a promise that users can rely on (see my thoughts in an earlier blog on tagging/versioning images).

[...] is it just a perceptual one or do you see anything code related there?

Imagine me saying it with my German accent: "there are rules" :^) and the rules are defined by semver.org. I believe semver has helped tremendously in maintaining the container tools.

[vrothberg]

I just re-read the specification over my morning coffee and loved the pitch on Why using semver:

This is not a new or revolutionary idea. In fact, you probably do something close to this already. The problem is that “close” isn’t good enough. Without compliance to some sort of formal specification, version numbers are essentially useless for dependency management. By giving a name and clear definition to the above ideas, it becomes easy to communicate your intentions to the users of your software. Once these intentions are clear, flexible (but not too flexible) dependency specifications can finally be made

That's a much better explanation of why "more" or "close" are not enough.

[cgwalters]

Sure, I'm not objecting at all, just trying to flesh out what it means. Does someone want to take an action here to somehow implement this commitment?

I guess offhand it could be as little as a comment in the documentation somewhere and probably

diff --git i/lib/Cargo.toml w/lib/Cargo.toml
index df647b71..b214ec8d 100644
--- i/lib/Cargo.toml
+++ w/lib/Cargo.toml
@@ -5,6 +5,10 @@ license = "MIT OR Apache-2.0"
 name = "bootc-lib"
 readme = "README.md"
 repository = "https://github.com/containers/bootc"
+# While this project is not published as a crate, we will match
+# the commitments of semver. Note that because we almost always
+# add new features in releases, that means you should bump the
+# MINOR in the MAJOR.MINOR.MICRO version here. (ref https://semver.org/)
 version = "1.1.7"
 # In general we try to keep this pinned to what's in the latest RHEL9.
 # However right now, we bumped to 1.82 as that's what composefs-rs uses.

too

[jeckersb]

I'll codify the commitment